@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.1

package/README.md

@@ -1,3 +1,847 @@
-# Temporary Holding Version
+# @tego/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Everything needed to build, package and test a Tego plugin.
+
+Before this existed the only reference was `plugins/tego-crm`'s source, which
+meant every new plugin inherited that one's accidental decisions and each
+correction cost twice as much as the last. Read this instead; open CRM only for
+an example of a screen.
+
+- [What a plugin is](#what-a-plugin-is)
+- [Which part does what](#which-part-does-what)
+- [Package layout](#package-layout)
+- [The manifest](#the-manifest)
+- [`hostApiRange`](#hostapirange)
+- [Configuration](#configuration)
+- [Building and packaging](#building-and-packaging)
+- [The local loop](#the-local-loop)
+- [Testing](#testing)
+- [Developing outside this repository](#developing-outside-this-repository)
+- [Upload, install, run](#upload-install-run)
+
+## What a plugin is
+
+One archive with up to three parts, described by a single `tego.plugin.json` at
+its root. At least one part is required.
+
+| Part       | Runs                                | Written against                      |
+| ---------- | ----------------------------------- | ------------------------------------ |
+| `frontend` | In the shell, as a SystemJS module  | `@tego/plugin-sdk/frontend`          |
+| `backend`  | As a container the platform manages | `@tego/plugin-sdk/server-runtime`    |
+| `claw`     | Inside an avatar's claw container   | OpenClaw's own plugin SDK, unchanged |
+
+Start one with the scaffold rather than by copying:
+
+```bash
+pnpm plugin:new
+```
+
+It asks for an id, display names, a scope and which parts you want, then writes
+a package that passes upload validation as-is — manifest, ten locale bundles,
+and one working example per part.
+
+## Which part does what
+
+**The frontend part opens a full working page.** A record list, a detail view,
+a dashboard: things a person navigates to from the sidebar and works in. It
+owns every route under `/p/<pluginId>`.
+
+The sidebar gives you **one row**, named by your `displayName`, sitting in the
+扩展 flyout. It opens `/p/<pluginId>` and that is the last say the shell has:
+which page a user lands on, and how they move between your pages, is yours to
+render — a tab bar, a nav rail, whatever the work needs. The shell cannot
+publish your pages as rows of its own, because how many there are is decided by
+whoever installs plugins, and three plugins of four pages each would push the
+built-in sections off the screen.
+
+**Anything inside a conversation goes through the claw part**, driven by the
+avatar: a skill tells the agent when to act, and the agent draws cards with the
+platform's a2ui tools. Do not try to render into the chat from the frontend
+part — there is no seam for it, and the one that exists is claw's.
+
+**The backend part is the plugin's own service and its own data.** It gets a
+dedicated Postgres schema, a role scoped to it, and object storage under its own
+prefix. It is reachable only through the platform: the gateway authenticates the
+caller, checks the tenant and the permission, and forwards. No published port,
+no ingress route.
+
+A plugin does not need all three. A claw-only plugin is a normal thing to ship.
+
+### The identity your backend receives is verified for you
+
+Your `fetch(request, ctx, host)` is called with a `ctx` naming the user, their
+tenant, their roles and — when a claw container is calling — the avatar. You can
+authorize against all of it. `serveBackend` has already checked that the
+platform is what wrote it: the gateway signs the identity per request with a key
+derived for your install, and anything that does not verify gets a 401 without
+reaching your code.
+
+So do not accept identity from anywhere else. A `userId` in a query parameter,
+a body field or a header of your own is a caller-supplied string, and the whole
+point of `ctx` is that it is not. There is also no token to parse — the caller's
+credentials stop at the platform, which is what keeps a plugin from being a
+place the user's entire account can be driven from.
+
+### Your frontend needs its own error boundary
+
+The shell mounts you into a plain DOM node and wraps that node in a boundary,
+so a throw from `mount` itself, or from the shell's own work around it, shows
+an error page with the sidebar intact rather than taking the app down.
+
+That boundary cannot see inside you. You render into your own React root, and
+React contains a root's render errors within that root — the shell's boundary
+is never on the path. Without one of your own, a component that throws on the
+third tab leaves a blank rectangle and a console entry, which reads as the
+platform having lost the page.
+
+## Package layout
+
+```plaintext
+my-plugin/
+├── tego.plugin.json          # the manifest — the only required file
+├── frontend/
+│   ├── index.js              # SystemJS bundle, built by the SDK's vite preset
+│   └── i18n/<locale>.json    # all ten locales, see below
+├── backend/
+│   ├── index.js              # one call to serveBackend()
+│   └── migrations/*.sql      # append-only, applied by the host
+└── claw/
+    ├── openclaw.plugin.json  # an intact OpenClaw manifest
+    ├── index.js
+    └── skills/
+```
+
+Every path above is a default you can override in the manifest, but there is
+rarely a reason to. `tego-plugin-pack` produces exactly this from your sources.
+
+The ten locales are not negotiable for a part that ships UI. The platform
+serves `zh-CN zh-TW en ja ko de es fr it pt`; shipping two of them means a
+Japanese operator opens your plugin and finds the one screen in the product
+that is untranslated, which reads as the platform being half-finished. Upload
+refuses an incomplete set, where you can still act on it — a runtime fallback
+would hide the gap forever.
+
+## The manifest
+
+```jsonc
+{
+  "manifestVersion": 1,
+  "id": "acme-crm",
+  "version": "1.0.0",
+  "displayName": { "zh-CN": "客户关系", "en": "CRM" },
+  "scope": "avatar",
+  "hostApiRange": "^1.3.0",
+  "declares": { "database": true, "storage": true, "events": true },
+  "parts": {
+    "frontend": {
+      "icon": "handshake",
+      "nav": [
+        {
+          "key": "companies",
+          "labelKey": "nav.companies",
+          "icon": "building",
+          "path": "/companies",
+        },
+      ],
+    },
+    "backend": {},
+    "claw": {},
+  },
+}
+```
+
+**`scope`** decides who the plugin belongs to, and it is declared rather than
+inferred.
+
+- `avatar` — a capability of a digital avatar. Install picks which avatars get
+  it; its pages appear while one of those is the active avatar. A plugin with a
+  claw part is necessarily this, since a claw extension loads inside one
+  avatar's container.
+- `tenant` — a workspace application with no per-avatar meaning, open to
+  everyone in the tenant.
+
+**`declares`** is what the install screen tells the operator: a dedicated
+schema, object storage, `plugin.<id>.*` events. These are **disclosures, not
+grants**. Plugins are first-party and the frontend runs with the shell's own
+privileges, so calling them permissions would promise an isolation boundary
+that is not there. `database` is the one that also changes behaviour, because
+provisioning a schema is something the host does or does not do.
+
+**`nav` declares your pages, not sidebar rows.** The sidebar shows your plugin
+as one row that opens it at its root, and you route between your pages
+yourself. Leave `nav` empty and your frontend gets neither a row nor a page.
+
+**Access follows the avatars, not roles.** The host writes no role menu or
+permission for a plugin. An avatar-scoped plugin may be used by whoever may use
+an avatar it is installed on — an administrator, the avatar's owner, or someone
+granted `use` or above; view-only access does not count. A tenant-scoped plugin
+is open to the whole tenant. Access is all-or-nothing, so `ctx.can(key)` only
+says whether `key` is one of your nav entries; per-page and per-record rules
+belong in your access catalog (`@tego/plugin-sdk/access`).
+
+**`frontend.icon` is your sidebar icon**; the per-entry `icon` and `order` in
+`nav` are accepted for compatibility and not read. Icons come from a closed
+list (`PLUGIN_NAV_ICONS`): an arbitrary `lucide-react` name can only be
+resolved dynamically, which pulls the whole icon set into the shell's eager
+bundle to decorate rows most tenants do not have. Declare nothing and you get
+the generic plugin glyph.
+
+### Digital employee templates and work delegation
+
+An avatar plugin may ship template assets in its own package:
+
+```jsonc
+"agentTemplates": [{
+  "key": "safety-employee",
+  "entry": "templates/safety-employee/template.json",
+  "icon": "templates/safety-employee/avatar.png"
+}]
+```
+
+Author the template as a directory beside its entry: `template.config.json`
+(everything except workspace documents), `workspace/*.md` for the main agent's
+root files, other files under `workspace/` shipped at their relative path, and
+— when the config lists `agents`, main first — one `experts/<id>/` per expert.
+`tego-plugin-pack` rebuilds `template.json` from these before packing (commit
+the result); `tego-plugin-pack templates` rebuilds without packing. An entry
+with no `template.config.json` beside it is shipped as written.
+
+`tego-plugin-pack` copies only the declared files. Upload validates the template
+against the platform template schema. Approving a release publishes its
+templates for that tenant; retiring, revoking or archiving the last approved
+release hides them, and the tenant's catalog lists them only while the plugin
+is installed and enabled. The template row belongs to the release: admins can
+change its price, nothing else. The host adds the owning plugin to
+`strictRequiredPlugins`, so creation fails if it cannot bind the plugin to the
+new employee. Template content and portrait remain in the plugin package.
+
+Plugins using the host's work delegation API must declare a policy:
+
+```jsonc
+"workDelegation": { "allowedAvatarRoles": ["sales-assistant"] }
+```
+
+The host checks the installed release's policy when listing candidates,
+choosing a workspace default, enabling delegation and resolving an existing
+grant. Omission denies delegation; `"*"` permits any employee role. Revoking
+an existing grant remains possible when the employee is no longer eligible.
+
+The host owns the consent flow; plugins do not build grant or revoke buttons.
+A person grants per employee in a host dialog that states what the employee
+may do and the backend's declared `egress`. The dialog opens on its own the
+first time the person enters the plugin with an employee they have not
+granted; declining keeps the plugin usable and the host does not prompt again
+for that employee. Describe the work in the dialog with optional fields:
+
+```jsonc
+"workDelegation": {
+  "allowedAvatarRoles": ["sales-assistant"],
+  "summary": { "zh-CN": "员工会读取你可见的客户…", "en": "Reads the companies you can see…" },
+  "privacyPolicyUrl": "https://example.com/privacy",
+  "conversationCapture": true
+}
+```
+
+`summary` is at most 120 characters per locale. `privacyPolicyUrl` must be
+https. `conversationCapture: true` adds an unticked option to record the
+person's new conversations with the employee, for plugins that read
+`host.sources`. These fields need `hostApiRange` `^1.33.0` or later.
+
+From 1.33 the frontend reads the state from `ctx.delegation` and calls
+`ctx.delegation.open()` wherever work needs the grant; the promise resolves
+with the state once the dialog closes:
+
+```ts
+const state = ctx.delegation?.current(); // status: granted | not_granted | not_ready | ineligible | no_employee | loading
+if (state?.status !== 'granted') {
+  const next = await ctx.delegation?.open();
+  if (next?.status !== 'granted') return;
+}
+```
+
+`ctx.delegation` is present only when the manifest declares `workDelegation`
+and `hostApiRange` starts at 1.33 or later. Plugins without a frontend need
+nothing more: the usage guide entry below opens the same dialog. Delegation
+is judged by your backend through the signed `delegation` on machine
+requests, so the manifest is rejected when `workDelegation` has no backend part. Grants
+and revocations are recorded in the governance audit with the release
+version; a plugin upgrade does not ask people to grant again.
+
+The host also lists delegation in the employee's usage guide: for every person
+using an eligible employee it adds the setup item
+`plugin:<pluginId>:work_delegation`, `ready` once that person has delegated.
+Its button opens the host dialog. `settingsRoute` is deprecated: the host no
+longer links the item to a plugin page. Template quick prompts can name the
+item in `requires`. Do not report delegation from your own readiness route.
+
+Plugins that need people to finish something before an employee can work for
+them report it per person:
+
+```jsonc
+"agentReadiness": { "path": "readiness" }
+```
+
+`path` is a backend route relative to the plugin root, so the manifest needs a
+backend part. Declaring `agentReadiness` or `workDelegation.settingsRoute`
+requires `hostApiRange` `^1.30.0` or later.
+
+The host calls the route as the viewing person, with `avatarId` in the query,
+and expects `{ "items": [...] }` (optionally wrapped in `data`). Each item has
+an `id` unique within the plugin, `title`, `status` (`ready`, `action_needed`,
+`not_applicable` hides the item and the quick prompts requiring it, `unknown`),
+`owner` (`self` or `other`), and optionally `why`, `ownerHint`, `optional` and
+`action: { label, route }`. Text fields accept `LocalizedText`; the host picks
+the viewer's locale, then `en`. `action.route` is a path inside your plugin.
+A response that fails validation, times out, repeats an id or uses
+`work_delegation` is shown as a single `unknown` item.
+
+Plugins that bind a business record to a conversation declare their read-only
+routes instead of adding entity names or paths to the host:
+
+```jsonc
+"conversationRecordRoutes": [
+  { "entity": "contact", "path": "contacts", "contextQuery": "context=pipeline" }
+]
+```
+
+The host calls the declared route with the URL-encoded record ID and the
+verified user context. The plugin remains responsible for record permission
+checks and the returned record and context projection.
+
+## `hostApiRange`
+
+A caret range over the shared-module surface the shell hands your frontend:
+React, `@tego/ui`, `react-i18next`, `lucide-react`,
+`@tego/chat/plugin-surface`. The current version is exported as
+`HOST_API_VERSION`.
+
+Declare the lowest version whose features you actually use, not the newest one
+available. `^1.0.0` keeps loading on every 1.x shell; `^1.3.0` says you need
+`PluginHostContext.events` and will be refused by a shell that predates it. A
+major bump refuses every plugin declaring an older range, which is the point —
+the alternative is failing inside a hook with a message about neither.
+
+Required once you ship a frontend or backend part. A claw-only plugin is
+governed by claw's own `minHostVersion` instead.
+
+## Roles and permissions inside your plugin (Host API 1.22)
+
+`nav` decides who may open your plugin; what they may do once inside is yours,
+and `@tego/plugin-sdk/access` is how you answer it. Accounts and host roles stay
+the host's. Your roles, their grants and who holds them live in your own schema,
+and the tenant's administrators edit them in a screen you embed. The model and
+the reasons behind it are in `docs/design/plugin-access.md`.
+
+Declare a catalog, validated by `tego-plugin-pack` against
+`@tego/plugin-sdk/access-catalog.schema.json`:
+
+```jsonc
+// tego.plugin.json
+{ "hostApiRange": "^1.22.0", "access": { "catalog": "shared/access.json" } }
+
+// shared/access.json
+{
+  "version": 1,
+  "groups": [{ "key": "records", "labelKey": "access.group.records" }],
+  "scopes": { "own": { "labelKey": "access.scope.own" }, "all": { "labelKey": "access.scope.all" } },
+  "permissions": {
+    "record.view": { "group": "records", "labelKey": "access.record.view", "scopes": ["own", "all"],
+                     "agent": { "requires": ["records.read"] } },
+    "record.delete": { "group": "records", "labelKey": "access.record.delete", "agent": { "allowed": false } }
+  },
+  "roles": {
+    "admin": { "nameKey": "access.role.admin", "grants": { "access.manage": true, "record.view": "all", "record.delete": true } },
+    "member": { "nameKey": "access.role.member", "grants": { "record.view": "own" } }
+  },
+  "hostRoleBindings": { "admin": ["admin"], "super_admin": ["admin"] },
+  "defaults": { "unassigned": "member" },
+  "assignment": { "principals": ["user", "unit"] }
+}
+```
+
+The build refuses a catalog that cannot work:
+
+- a reference to an undeclared permission or scope;
+- a menu key that is not in `nav`;
+- `unit` principals without `directory.read`;
+- a host `admin` who could not reach the access settings, which is the one
+  way a tenant locks itself out.
+
+On the backend, one engine per plugin and one session per request:
+
+```ts
+import { createAccess, accessCatalogFromJson } from '@tego/plugin-sdk/access';
+import { accessHono, assertRouteCoverage } from '@tego/plugin-sdk/access/hono';
+
+export const access = createAccess({
+  catalog: accessCatalogFromJson(catalogJson),
+});
+const { policy, routes } = accessHono({ session: c => c.env.access }); // access.forRequest(ctx, host)
+
+app.get('/records', policy.permission('record.view'), listRecords);
+app.delete(
+  '/records/:id',
+  policy.resource('record.delete', loadRecord, { conceal: true }),
+  deleteRecord
+);
+app.route('/', routes()); // /access/me, /access/roles, /access/assignments, …
+
+// in start(host): bring the built-in roles in line with the catalog
+await access.reconcile(host);
+```
+
+- **Every route carries exactly one policy.** Test it with
+  `assertRouteCoverage(app, { publicRoutes })`. An unmarked route fails the
+  test rather than defaulting to open.
+- **Lists go through the scope.** `session.filter('record.view', { alias: 'r' })`
+  returns the SQL condition for a list query. It comes from the same evaluator
+  that judges a single record, so the list and the detail page cannot disagree.
+- **`authorizeStorage` goes through the same engine:**
+  `access.forSubject(await access.subjectFor(userId, host), host)`.
+- **Background jobs never act as a user.** They are trusted system code; work
+  done for a person arrives through claw's `fetch`, with a delegation.
+- **The tables go in your migrations.** Re-export them from
+  `@tego/plugin-sdk/access/drizzle` and run `db:generate`; a Python backend uses
+  `@tego/plugin-sdk/access.sql`. Every table carries `tenant_id`, which
+  `host.tenantId` supplies.
+
+On the frontend, `@tego/plugin-access-ui` is bundled into your plugin, not
+shared by the shell:
+
+- mount `<AccessProvider api={ctx.api}>` under your own `QueryClientProvider`;
+- gate the UI with `useAccess()`, `<Can>` and `filterNav`;
+- embed `<AccessSettings />` in your settings;
+- add the package to your Tailwind `content`.
+
+`tego-plugin-pack` merges its strings into your ten locales under `tegoAccess`.
+What the frontend hides is presentation only: the backend is the boundary.
+
+Python backends get the same model, tables and `/access` contract from
+`tego_plugin_sdk.access`, with the FastAPI adapter in
+`tego_plugin_sdk.access.fastapi`: `AccessFastApi`, and `assert_route_coverage`.
+
+## Configuration
+
+Three sections, declared and stored separately: `frontend`, `backend`, `claw`.
+They are never merged. Which section a value is in decides who ever sees it, so
+the separation is the security property rather than a filing convention.
+
+```mermaid
+flowchart LR
+  fe["parts.frontend.config"] --> store["stored per install,<br/>three rows"]
+  be["parts.backend.config"] --> store
+  claw["configSchema in<br/>claw/openclaw.plugin.json"] --> store
+  store -->|"with discovery"| feOut["the browser"]
+  store -->|"host API, on startup"| beOut["the backend container"]
+  store -->|"merged with per-avatar overrides"| clawOut["the avatar's openclaw.json"]
+```
+
+Declare the frontend and backend sections in `tego.plugin.json`:
+
+```jsonc
+"backend": {
+  "config": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "apiBaseUrl": { "type": "string", "format": "uri" },
+        "apiKey": { "type": "string", "minLength": 8 }
+      },
+      "required": ["apiBaseUrl", "apiKey"],
+      "additionalProperties": false
+    },
+    "uiHints": {
+      "apiKey": {
+        "label": { "zh-CN": "接口密钥", "en": "API key" },
+        "sensitive": true
+      }
+    }
+  }
+}
+```
+
+**Do not declare the claw section here.** `claw/openclaw.plugin.json` already
+carries a `configSchema` that claw itself validates against; a second
+declaration would be a second truth about the same fields.
+
+### The allowed schema is narrow
+
+A flat object of scalars, string enums and string arrays. No nesting, no
+`$ref`, no unions. Two reasons, and the second is load-bearing:
+
+- The form renders without you previewing it. Anything the renderer would fall
+  back to a JSON textarea for is a field the operator fills by typing JSON,
+  which is not a form.
+- Per-avatar claw overrides merge at top-level key granularity, because
+  deep-merging objects and arrays has no single obvious semantics. A nested
+  object would be replaced wholesale by an override, which is not what its
+  shape suggests.
+
+### Secrets
+
+Mark a field `sensitive` and it is stored encrypted, never returned in
+plaintext, and never placed in the container's environment. Reads substitute
+`__OPENCLAW_REDACTED__`; writing that value back means "keep what is stored", so
+saving a form does not require retyping a key nobody was shown.
+
+`sensitive` in the **frontend** section is a validation error, not a stripped
+flag: everything that section contains is delivered to the browser, so a secret
+there is public by construction.
+
+### How each part reads its own
+
+Frontend, already resolved when the surface mounts:
+
+```ts
+export default definePluginFrontend({
+  mount(el, ctx) {
+    const endpoint = ctx.config['apiBaseUrl'];
+  },
+});
+```
+
+Backend, fetched over the host API before the first request is accepted:
+
+```ts
+const { apiKey } = host.config.current();
+await host.config.refresh(); // for a rotated credential, without a restart
+```
+
+Environment variables are deliberately not the channel. A secret in the
+environment appears in `docker inspect`, in the orchestrator's API and in crash
+dumps, and it is fixed at container creation — rotating a key would mean
+recreating the container.
+
+Claw reads its section from the avatar's `openclaw.json`, where the platform
+projects the tenant default with that avatar's overrides applied.
+
+### Required and unset
+
+A **backend** field that is required and unfilled leaves the install in
+`awaiting_config`: installed, no container started, and calls answered with an
+explanation instead of a 502. Filling it in starts the backend. Only the backend
+section can hold anything back — a missing frontend setting is a page that
+renders wrong, and a missing claw setting is claw's business.
+
+An upgrade whose new schema rejects the stored values puts the backend back into
+`awaiting_config` rather than starting it on a value it will choke on.
+
+## Building and packaging
+
+```bash
+pnpm exec tego-plugin-pack            # from the package root
+pnpm exec tego-plugin-pack --watch    # frontend rebuild loop, see below
+```
+
+The packer owns the archive layout because that layout is the platform's
+contract: the server reads `tego.plugin.json`, resolves the part defaults, and
+expects the bundle, the migrations and the claw subtree at exactly those paths.
+It builds the frontend with Vite through the SDK's preset, bundles the backend
+and claw entries with esbuild, and writes a deterministic ZIP.
+
+Your `vite.config.ts` is one call:
+
+```ts
+import { tegoPluginFrontend } from '@tego/plugin-sdk/vite';
+
+export default tegoPluginFrontend({ entry: 'src/index.tsx' });
+```
+
+The preset is not a convenience wrapper. The shell can only load a SystemJS
+module whose shared imports were rewritten to the exact ids it registered, and
+both of those are one-line mistakes that build cleanly and fail at load with a
+message about an unknown scheme.
+
+### Styling with Tailwind
+
+A plugin that compiles its own utilities passes `tegoPluginTailwind` to
+`tailwindcss` (the plugin's own dependency):
+
+```ts
+import { resolve } from 'node:path';
+
+import { tegoPluginFrontend, tegoPluginTailwind } from '@tego/plugin-sdk/vite';
+import tailwindcss from 'tailwindcss';
+
+const config = tegoPluginFrontend({ entry: 'frontend/src/index.tsx', pluginId: 'acme-crm' });
+config.css = {
+  postcss: {
+    plugins: [
+      tailwindcss(
+        tegoPluginTailwind({
+          pluginId: 'acme-crm',
+          root: import.meta.dirname,
+          content: [resolve(import.meta.dirname, 'src/**/*.{ts,tsx}')],
+        })
+      ),
+    ],
+  },
+};
+export default config;
+```
+
+It takes the design tokens from `@tego/ui`'s preset (the one the shell compiles
+with), leaves the reset to the shell, scopes every utility under `.<pluginId>`,
+and compiles the classes of `@tego/ui` and `@tego/plugin-access-ui` components
+the bundle uses. Packages resolve from `root`, so the same call works in this
+repo and in a standalone one. Do not load a `tailwind.config.js` by relative
+path: outside this repository there is nothing at that path.
+
+For anything the conventions cannot infer, call `packPlugin` from a script:
+
+```ts
+import { packPlugin } from '@tego/plugin-sdk/pack';
+
+await packPlugin({ root: process.cwd(), backend: { external: ['sharp'] } });
+```
+
+## The local loop
+
+Without this, changing one line of frontend code costs a pack, an upload, an
+install and a refresh.
+
+```bash
+pnpm exec tego-plugin-pack --watch                    # serves the bundle on :5180
+VITE_TEGO_LOCAL_PLUGINS=acme-crm=http://localhost:5180/index.js pnpm -F @tego/ai-studio dev
+```
+
+Saving a file rebuilds and reloads the plugin page. The release still supplies
+everything else — nav entries, permissions, version — only the bundle's origin
+changes, and the override is compiled out of a production build entirely.
+
+There is **no module-level HMR**. State inside the page is lost on each rebuild.
+Hot replacement across the SystemJS boundary means unmounting the plugin's React
+root and re-registering shared modules, which is a lot of machinery for
+something that would silently desync; a one-second reload is always right.
+
+The backend runs on the host instead of in a container:
+
+```bash
+TEGO_PLUGIN_BACKEND_BASE_URL=http://localhost:18800 pnpm -F @tego/server dev
+
+pnpm -F @tego/server exec tsx scripts/run-plugin-backend-locally.ts \
+  acme-crm "$PWD/plugins/acme-crm/build/acme-crm-1.0.0.zip"
+```
+
+The platform then adopts the process at that address rather than starting a
+container it could not reach from the host. The port is fixed at 18800, and the
+zip path has to be absolute — `pnpm exec` runs with `apps/server` as its working
+directory. The plugin must already be installed; the script reads its schema
+name and host API token from that install.
+
+## Testing
+
+The interesting code in a plugin backend is its SQL — multi-table writes in one
+transaction, `FOR UPDATE SKIP LOCKED`, partial unique indexes — and none of that
+means anything against a fake. `createTestPluginHost` stands up the real thing:
+
+```ts
+import { createTestPluginHost } from '@tego/plugin-sdk/testing';
+
+const harness = await createTestPluginHost({
+  pluginId: 'acme-crm',
+  migrationsDir: new URL('../migrations', import.meta.url).pathname,
+  config: { apiBaseUrl: 'https://example.test' },
+});
+afterAll(() => harness.close());
+beforeEach(() => harness.reset());
+
+const response = await backend.fetch(request, userContext, harness.host);
+expect(harness.publishedEvents).toEqual([...]);
+```
+
+A throwaway schema with your migrations applied, behind the same
+`PluginScopedDb` the host hands a running backend — including real transactions
+on one connection, which is the thing most easily got wrong: a body whose
+statements land on pooled connections is not a transaction, and a double would
+let that pass.
+
+`harness.failPublish()` makes `events.publish` throw, which is the only way to
+reach the case where a failed announcement undoes a committed write.
+
+## Developing outside this repository
+
+Three SDK packages are published to npm under `@zhama/tego-*` and installed
+under their workspace names with npm aliases, so imports and `$schema` paths
+read exactly as they do inside this repository:
+
+```json
+"devDependencies": {
+  "@tego/plugin-sdk": "npm:@zhama/tego-plugin-sdk@^1.35.0",
+  "@tego/ui": "npm:@zhama/tego-ui@^1.35.0",
+  "@tego/plugin-access-ui": "npm:@zhama/tego-plugin-access-ui@^1.35.0"
+}
+```
+
+`@tego/plugin-access-ui` is only needed by a plugin that shows access
+settings. The TypeScript presets and the lint config are not packages: the
+scaffold writes them into the plugin (`tsconfig.base.json`,
+`tsconfig.frontend.json`, `tsconfig.backend.json`, `eslint.config.js`). They
+drive the editor, `tsgo` and ESLint only — the build is the SDK's — so change
+them as you like.
+
+The alias is required, not cosmetic: `@tego/ui` is a shared module id the shell
+resolves your imports against, and the `@tego` scope on the public registry
+belongs to another project. Never install a plain `@tego/*` package from npm.
+
+Start from the scaffold instead of by hand. The SDK ships it as
+`tego-plugin create`, so no checkout of this repository is needed: it writes
+all of the above, `.prettierrc.json`, `.gitignore` and a `pnpm-workspace.yaml`
+that allows esbuild's install script, into `<dir>/<id>/`. The answers come as
+JSON on stdin (`scope` is `avatar` or `tenant`, default `avatar`), and
+`hostApiRange` follows the SDK you run:
+
+```bash
+echo '{"id":"acme-notes","displayNameZh":"笔记","displayNameEn":"Notes",
+       "descriptionZh":"…","descriptionEn":"…","parts":["frontend","backend"]}' \
+  | npx -p @zhama/tego-plugin-sdk tego-plugin create --dir ~/code
+cd ~/code/acme-notes && pnpm install
+```
+
+Inside this repository `pnpm plugin:scaffold --standalone ~/code` does the
+same, and `pnpm plugin:new` writes the in-repo (`workspace:*`) variant; all
+three use `@tego/plugin-sdk/scaffold`. Tego Studio creates plugins with
+`tego-plugin create` too.
+
+**Versions.** Every package is released at one version whose major.minor is
+`HOST_API_VERSION`. A manifest declaring `"hostApiRange": "^1.35.0"` installs
+`^1.35.0` of the SDK; raise both together when you start using a newer host
+API.
+
+**The chat surface.** `@tego/chat/plugin-surface` (an agent conversation
+embedded in a plugin page) is available only to plugins built inside the Tego
+repository. It is not published and the SDK carries no types for it.
+
+**License.** The published packages are under the Tego Plugin SDK License
+(`LICENSE` in each package): free to use for building, testing and
+distributing plugins that run in Tego, not for other products, and not
+redistributable on their own. Your plugin's own code stays yours.
+
+**Toolchain.** Inside the repo the root `package.json` provides `tsgo`,
+`eslint`, `prettier` and `typescript`. A standalone repository installs them
+itself; the scaffold pins the same versions.
+
+Releasing these packages is `pnpm sdk:publish` from the repo root (see
+`scripts/sdk-release/`); `node scripts/sdk-release/smoke.mjs` proves a
+standalone plugin installs, checks, tests and packs against the staged
+tarballs with both npm and pnpm.
+
+## Upload, install, run
+
+1. **Pack.** `pnpm exec tego-plugin-pack` writes `build/<id>-<version>.zip`.
+2. **Upload**, in the admin plugin screen. Everything that can be checked is
+   checked here, where you can still fix it: the manifest, the schema subset,
+   the ten locales, the icon names, the nav key lengths. An uploaded release is
+   a `draft` until approved.
+3. **Approve**, which makes the release installable.
+4. **Install.** The operator picks the avatars (for an avatar-scoped plugin),
+   reads what the plugin declares, and fills in the three configuration
+   sections. Install writes the menu and permission rows, provisions the schema,
+   applies the migrations and starts the backend — unless a required backend
+   setting is missing, in which case it lands in `awaiting_config`.
+5. **Upgrade** by installing a newer release over the same plugin id. The screen
+   shows what this version discloses beyond the accepted one. Stored
+   configuration is re-validated against the new schema.
+
+A **downgrade is refused** before anything is written: a release that does not
+contain a migration this tenant has already applied cannot be installed, because
+the data those migrations produced cannot be rolled back automatically.
+Uninstall first if the intent is to start over — which does drop the schema.
+
+### One command, for iteration and CI
+
+Steps 1–4 are also a single non-interactive command. It packs the current tree,
+streams the archive through the same presigned upload the screen uses, finalizes
+the release, approves it, and installs it onto the tenant:
+
+```bash
+pnpm exec tego-plugin publish \
+  --server http://localhost:3100 \
+  --token "$TEGO_ADMIN_TOKEN" \
+  --avatar av_123            # repeat per avatar; avatar-scoped plugins only
+```
+
+`--server` and `--token` fall back to `TEGO_SERVER_URL` and `TEGO_ADMIN_TOKEN`.
+The token is an admin session's bearer — the publish endpoints all sit behind
+the same admin guard as the screen. `--no-approve` stops at a draft;
+`--no-install` approves without installing. There is no separate downgrade or
+config path here: those decisions belong on the screen, and this command
+deliberately does not reach for them.
+
+### 通用 AI 表单填写（Host API 1.9）
+
+宿主为所有插件页面提供统一悬浮按钮。插件登记当前可编辑表单，无需实现 AI 输入框、模型调用或聊天窗口。支持 React、Vue 及原生前端；`frontend` 入口不依赖 React。
+
+```ts
+const unregister = ctx.ai?.registerForm({
+  id: 'inventory-edit',
+  title: '库存调整',
+  element: formElement,
+  getSnapshot: () => ({
+    fields: [
+      { name: 'quantity', label: '数量', type: 'number', value: state.quantity },
+      { name: 'note', label: '说明', type: 'text', value: state.note },
+    ],
+    instructions: '数量使用件，不推测未提供的数量。',
+  }),
+  apply: values => updateLocalForm(values),
+});
+// 关闭表单/卸载组件时调用；不要在每次输入变化时重新注册。
+unregister?.();
+```
+
+`element` 必须已经挂载。React 的弹窗可能延迟挂载 portal，建议用 callback ref 取得元素，再在 effect 内登记。`getSnapshot` 必须读最新状态；React 可以用 ref 保存当前表单值。
+
+字段类型为 `text`、`number`、`boolean`、`date`、`select`；枚举提供 `options: [{ value, label }]`。只登记当前可见、可编辑、允许提供给分身的字段；不登记密码、令牌、隐藏字段。业务枚举和规则由插件声明，SDK 不内置任何具体插件的数据模型。
+
+宿主调用所选分身的独立 model-only 运行，使用完成回执回填，不发聊天消息、不赋予工具写权限。回填前检查字段类型和枚举，保留运行期间手工编辑的字段；关闭表单或切换分身会取消，迟到结果丢弃。嵌套表单优先作用于最后登记的表单，关闭后恢复上一张。
+
+`apply` 只更新本地状态，不能提交或写数据库。用户继续通过原表单的校验和保存路径提交。没有登记表单的旧插件仍能显示统一入口，但会提示先打开已接入的表单。`ctx.ai` 是可选能力，可兼容旧宿主；需要保证可用的插件应声明 `hostApiRange: ^1.9.0`。
+
+单次填写通过有长度上限的运行回执返回，宿主要求简洁 JSON；过长、格式错误或不属于当前表单的输出会拒绝回填，不能保存部分损坏结果。
+
+## 受管下载（Host API 1.15）
+
+Host API 1.20.0 增加可选 `host.diagrams`：安装声明 `diagrams.render` 后，
+调用 `status()` 检查渲染器就绪，再以 `render({ kind: 'mermaid' | 'html', source,
+destinationKey, width?, height? })` 取得 PNG 的命名空间内 key、尺寸、哈希和渲染器版本。
+宿主不接收服务器路径或远程页面地址；HTML 只允许静态结构和受限样式，Mermaid 禁止
+配置覆盖与链接。渲染隔离、外网关闭、画布越界报错，默认限时 15 秒、并发 2。
+插件在后台任务保存幂等键、租约和章节版本，并重新校验项目权限后发布结果。
+
+需要下载时重新授权的插件声明 `storage.managed`，并使用
+`host().storage.managedPath(key, policy, ttlSeconds)`；Python 对应
+`host().storage.managed_path(key, policy, ttl_seconds)`。policy 包含主体、客户、
+resourceType/resourceId 和 purpose（view 或 export）。有效期最多 300 秒。
+
+每次 GET 或 Range 请求开始前，宿主向固定
+`POST /api/internal/storage/authorize` 发送带安装签名的策略。
+插件必须实时核验授权及 key 与资源的归属，并返回 `{ allowed: true }` 才能下载。
+SDK 单独验签并提供 storage policy 上下文；该上下文没有普通用户或公开身份，
+且不能访问其他业务路由。旧 signedPath 继续兼容未声明受管存储的插件。
+
+该机制约束每次新下载；已经通过授权而开始的传输可以完成。策略回调失败、
+超时或拒绝时，宿主不打开文件流。
+
+### 打开插件的 Office 产物
+
+Host API 1.21.0 提供可选 `ctx.office.open({ sourcePath, signal? })`。`sourcePath`
+只能指向当前插件自己的后端元数据接口；接口先校验业务权限，再返回
+`{ fileName, sha256, sizeBytes, downloadPath }`。`downloadPath` 必须由
+`storage.managedPath` 签发，宿主复核安装所属插件、实时下载权限、文件长度和 SHA-256，
+不接收本机路径、外部 URL 或资料库文档 ID。
+
+Office 打开该字节快照的独立副本，保存不会写回插件正式产物。分页为近似效果，
+打印验收仍由对应 Office 应用完成。单次预览读取配额为 64 MiB，超过时应选择分册
+或下载到本地；此限制不影响插件保存和导出长文。旧宿主没有 `ctx.office`，插件须做
+能力检测并保留下载入口。
+
+### 直接注册普通用户
+
+Host API 1.17.0 提供 `host.accounts.provisionUser`（Python：`host().accounts.provision_user`），需声明 `accounts.provision`。传入 `requestId`、`organizationName` 及用户身份；新用户同时传入 `password`，至少 8 位并包含大小写字母和数字。平台使用安装上下文的租户，复用配额和普通用户角色校验，在同一事务保存密码哈希及幂等结果，不发送邮件。已有用户可通过 `userId` 指定，或由平台按该租户邮箱匹配；已有账号的密码及身份资料不被覆盖。返回 `{ id, userId }`。插件须在调用前验证操作者的企业管理权限，且不持久化明文密码。
+
+Host API 1.18.0 提供 host.accounts.resetPassword({ userId, newPassword })（Python：host().accounts.reset_password(user_id, new_password)），须声明 accounts.provision。租户由安装凭证确定；仅允许重置有效普通平台账号，平台管理员账号必须在 Tego 平台管理。密码至少 8 位并包含大小写字母和数字。宿主复用正式密码服务，本地账号下次登录必须修改密码，第三方登录账号按平台认证规则处理。插件必须先校验操作者对目标企业成员的管理权限，不能持久化或记录明文密码。
+
+### 用事件启动员工的定时任务
+
+Host API 1.26.0 提供可选 `host.proactive.emit({ userId, eventType, eventId, occurredAtMs?, payload? })`（Python：`host().proactive.emit(user_id=..., event_type=..., event_id=...)`），须声明 `proactive.emit` 并有后端部分，`hostApiRange` 至少 `^1.26.0`。宿主把来源固定为 `plugin:<pluginId>`，只启动该用户在本租户已启用、`schedule` 为 `{ kind: 'event', source: 'plugin:<pluginId>', eventType }` 的定时任务；返回 `{ source, runs }`，每个命中的任务一条结果。同一 `eventId` 重发返回已排队的运行；任务正在运行时返回 `reason: 'already-running'`，本次不排队。`payload` 以外部不可信内容交给员工。详见 [plugin-sdk-api.md](../../plugins/docs/plugin-sdk-api.md#事件触发任务)。