@zhama/tego-plugin-sdk 1.37.1 → 1.40.0

package/README.md

@@ -606,12 +606,18 @@ install and a refresh.
 ### Preview without a Tego server: `tego-plugin dev`
 
 ```bash
-pnpm run dev                                            # scaffolded plugins have "dev": "tego-plugin dev"
-DATABASE_URL=postgres://me:pw@localhost:5432/dev pnpm run dev   # with the backend
+DATABASE_URL=postgres://me:pw@localhost:5432/dev pnpm run dev   # scaffolded plugins have "dev": "tego-plugin dev"
+DATABASE_URL=… pnpm run dev -- --inspect                        # the backend under the Node inspector (9229)
+pnpm run dev -- --no-backend                                    # the frontend alone
 ```
 
-It prints the address (`http://127.0.0.1:5280/p/<id>/`, or the next free port;
-`--port 0` takes any) and a machine-readable `TEGO_DEV_READY {"url":…}` line.
+The backend runs for real, as in any development loop; only tego-os around it
+(the host API and the gateway's signature) is a stand-in. A plugin with a
+backend therefore needs `DATABASE_URL`: without it, or when the database cannot
+be reached, the preview stops at once and says why instead of serving a page
+whose API calls fail. It prints the address (`http://127.0.0.1:5280/p/<id>/`,
+or the next free port; `--port 0` takes any) and a machine-readable
+`TEGO_DEV_READY {"url":…}` line once the backend answers its health path.
 Everything is served from that one origin:
 
 - **Frontend**: a stand-in for the shell's plugin page mounts your entry from
@@ -622,22 +628,31 @@ Everything is served from that one origin:
   (your locale files, the access UI's strings merged in), light/dark, and the
   user and roles the API calls are made as (`ctx.can` answers for any nav key
   the manifest declares).
-- **Backend** (with `DATABASE_URL`, unless `--no-backend`): built with the
-  packer's own settings and started with the environment `serveBackend` reads.
+- **Backend** (unless `--no-backend`): built with the packer's own settings
+  plus inline source maps and started as `node --enable-source-maps` with the
+  environment `serveBackend` reads; its output is printed line by line after
+  `[backend]`. With `--inspect[=<port>]` (or `TEGO_DEV_INSPECT`) it runs under
+  the Node inspector on 127.0.0.1, the same port after every restart.
   Requests carry the same signed identity headers the gateway adds. Migrations
   run first, each file in its own transaction with `search_path` set to
   `tego_dev_<id>` alone, recorded in a `tego_dev_migrations` table in that
   schema so each file runs once; the backend's connection is pinned to the
   schema too. Saving under `backend/` or `shared/` rebuilds, migrates and
-  restarts it. The database is yours to provide; any PostgreSQL works.
+  restarts it; if it crashes it waits for the next save. The database is yours
+  to provide; any PostgreSQL works (in a tego-os checkout, `pnpm infra:up`).
 - **Host API stand-in**: `config` (the backend section's defaults), `log`,
   `storage` (files under `.tego-dev/storage/`), `events` and `notifications`
   (printed), and a `directory` that knows the users you previewed as. Anything
   else — mail, knowledge, accounts, delegations, AI, Office, live events —
   answers 501 naming the path; test those on a real server.
 
-Without `DATABASE_URL` the page still works and API calls answer 503 saying
-why. `.tego-dev/` holds the generated shell, the backend build and local
+Saves are picked up through file events; on a machine out of them (macOS
+reports EMFILE when editors, Docker and other dev servers hold every FSEvents
+stream) the preview polls instead and says so, and `TEGO_DEV_POLL=1` forces
+polling.
+
+With `--no-backend` the page still works and API calls answer 503 saying why.
+`.tego-dev/` holds the generated shell, the backend build and local
 storage; keep it out of git. Python backends run on a server only.
 
 ### Inside the shell
@@ -701,6 +716,30 @@ 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.
 
+## The platform's rules, for people and agents
+
+The SDK ships the rules a plugin must follow, in the version it builds against:
+
+- `agent/RULES.md` lists every rule; `agent/guides/*.md` explains each area;
+  `agent/skills/*/SKILL.md` are step-by-step playbooks for common changes (a
+  route with access control, a screen, a migration, strings, a claw tool, an
+  agent template). A new plugin's `AGENTS.md` points coding agents at them.
+- `tego-plugin doctor` checks the rules that can be checked (`--json` for
+  tools; every finding carries a rule id, the guide and a line-independent
+  `fingerprint`).
+- `tego-plugin check` runs doctor, then the plugin's own lint, type-check and
+  test (`--build` adds build) as one report; the scaffold's `check` script
+  calls it. `--json --files a,b` is what editors and agents use.
+- `tego-plugin rules --json` (and the built `agent/rules.json`) lists every rule
+  with the files it applies to, resolved to the plugin's part folders.
+- `@tego/plugin-sdk/eslint` turns the line-level rules into ESLint core-rule
+  configuration, so the editor flags them while you type:
+
+  ```js
+  import { tegoPluginEslint } from '@tego/plugin-sdk/eslint';
+  export default [...yourConfig, ...tegoPluginEslint()];
+  ```
+
 ## Developing outside this repository
 
 Three SDK packages are published to npm under `@zhama/tego-*` and installed

package/agent/RULES.md

@@ -7,14 +7,18 @@ in both shells. Read the guide named in each section before writing that kind of
 
 Rules with an id are checked by `tego-plugin doctor` (`--json` for tools). A line can opt out with
 `tego-doctor-ignore <RULE-ID>: <reason>` on it or on the line above; give a real reason.
+`tego-plugin check` runs doctor and the plugin's lint, type-check and test as one report;
+`agent/rules.json` (or `tego-plugin rules --json`) lists every rule with the files it applies to;
+`agent/skills/` holds step-by-step playbooks for common changes.
 
 ## Working loop
 
-1. Read the relevant guide (`agent/guides/*.md`) and the code you change.
+1. Read the relevant guide (`agent/guides/*.md`) or playbook (`agent/skills/*/SKILL.md`) and the
+   code you change.
 2. Make focused changes; reuse the SDK's helpers (`@tego/plugin-sdk/react`, `/hono`, `/testing`)
    instead of writing your own versions.
-3. Run the gates: `tego-plugin doctor`, then lint, type-check, test, build. Fix everything they
-   report; never weaken a check or a test to make it pass.
+3. Run the gates: `tego-plugin check` (doctor, lint, type-check, test), and build before you
+   hand the plugin over. Fix everything they report; never weaken a check or a test to make it pass.
 4. Every new user-visible string goes into all ten locales.
 
 ## Manifest and packaging — guides/manifest.md, guides/host-api-versions.md
@@ -30,7 +34,7 @@ Rules with an id are checked by `tego-plugin doctor` (`--json` for tools). A lin
   or workspace links. On npm, a plain `@tego/*` name belongs to another project.
 - **TP-PKG-002** `package.json` has the four gates: `lint`, `type-check` (tsgo), `test` (vitest),
   `build` (`tego-plugin-pack`).
-- Never import `@tego/shared`, host app code, or anything not published to plugins.
+- **TP-PKG-003** Never import `@tego/shared`, host app code, or anything not published to plugins.
 
 ## Running in the web app and the desktop app — guides/desktop-web.md
 
@@ -49,7 +53,8 @@ that works in a browser tab can fail on desktop, and the reverse.
 - **TP-WEB-001** The frontend calls no third-party URL (the web CSP only allows the platform). The
   backend calls it, with the host declared in `parts.backend.egress`.
 - **TP-WEB-002** No remote or injected scripts; all code ships in the bundle.
-- No cookie-based auth: `ctx.api` carries the credentials in both shells.
+- **TP-WEB-004** No cookie-based auth (`document.cookie`, `hono/cookie`): `ctx.api` carries the
+  credentials in both shells.
 
 ## Frontend — guides/frontend.md
 
@@ -59,7 +64,8 @@ that works in a browser tab can fail on desktop, and the reverse.
   `AccessProvider` (with access) → `HostProvider`; the root element carries the scope class.
 - Route with `ctx.route` / `ctx.navigate` under `ctx.basePath`; the page is not remounted when the
   in-plugin path changes.
-- Call your backend only through `ctx.api` (via `createApiClient`), keeping the error body.
+- **TP-WEB-003** Call your backend only through `ctx.api` (via `createApiClient`), keeping the
+  error body; never a raw `fetch('/…')`.
 
 ## UI and design — guides/ui.md
 
@@ -70,6 +76,9 @@ that works in a browser tab can fail on desktop, and the reverse.
   `tegoPluginScopeRoot`) carries `className="<pluginId>"`, or none of your utilities apply.
 - Status uses text or an icon, not color alone; machine data (ids, numbers, times) uses
   `font-mono tabular-nums`.
+- **TP-UI-005** Copy stays short (zh-CN): an explanation (`*Help`, `*Hint`, `*description`,
+  `*subtitle`, `*intro`) at most 24 characters, any string at most 40; longer explanations go into
+  an `InfoTip`. An empty state is one sentence and one action.
 
 ## i18n — guides/i18n.md
 
@@ -78,17 +87,19 @@ that works in a browser tab can fail on desktop, and the reverse.
 - **TP-I18N-002** Every value keeps the `{{placeholders}}` of `zh-CN` and is not empty.
 - **TP-I18N-003** Every literal `t('…')` key exists.
 - **TP-I18N-004** Say 数字员工 / Employee through `{{avatarTerm}}`; never 数字分身 / digital avatar.
-- Keys live under one root named after the plugin (`notes.home.title`); don't copy `tegoAccess.*`.
+- Keys live under one root named after the plugin (`notes.home.title`).
+- **TP-I18N-005** Don't copy `tegoAccess.*` into the plugin's locales; pack merges them.
 
 ## Backend — guides/backend.md, guides/storage.md
 
 - **TP-BE-001** The caller is the verified `ctx` that `serveBackend` hands you. Never read the raw
   `x-tego-plugin-*` headers; a user id in a path or body names a target, never the caller.
 - **TP-BE-005** Log through `host.log`, never `console`.
-- Every error becomes JSON (`pluginErrorHandler`): coded 4xx for the caller's mistakes, a generic
-  500 that never echoes SQL; host 429s pass through with `Retry-After`.
+- **TP-BE-007** Every error becomes JSON (`app.onError(pluginErrorHandler())`): coded 4xx for the
+  caller's mistakes, a generic 500 that never echoes SQL; host 429s pass through with `Retry-After`.
 - Validate every body and query with zod (`readBody` / `readQuery`).
-- Data lives in your schema only (`host.db`); configuration in `host.config.current()`, never env.
+- **TP-BE-006** Data lives in your schema only (`host.db`); configuration in
+  `host.config.current()`, never `process.env`.
 - Storage: `put` up to 25 MiB; larger files upload from the browser to `uploadPath` and are
   verified with `head`. Download paths are `signedPath` / `managedPath`, opened via `ctx.hostUrl`.
 - Background work in `start()` never acts as a user.
@@ -120,4 +131,16 @@ that works in a browser tab can fail on desktop, and the reverse.
 
 - **TP-TEST-001** The plugin has tests: backend routes against a real database
   (`createTestPluginHost`), pure frontend logic in `.ts` files. No component tests.
-- Each test file starts with a Business Cases list; each `it` title starts with its case id.
+- **TP-TEST-002** Each test file starts with a Business Cases list; each `it` title starts with its
+  case id.
+
+## Agent templates — guides/agent-templates.md
+
+- Templates live in `templates/<key>/` (`template.config.json`, `workspace/*.md`, `experts/<id>/`)
+  and are declared in `agentTemplates`; `template.json` is built by `tego-plugin-pack`, never by
+  your own script.
+- **TP-TPL-001** When a template's content, `usageGuide` or `quickPrompts` change, raise its
+  `version`: existing employees only see the update through it.
+- **TP-TPL-002** `usageGuide.summary` is at most 30 characters; `quickPrompts` offers 3–4 prompts.
+- `setup` lists only what the host can check (`envVar`, `knowledgeBase`, `plugin`); plugin-specific
+  readiness comes from the manifest's `agentReadiness`.

package/agent/guides/agent-templates.md

@@ -0,0 +1,51 @@
+# Agent templates
+
+A plugin can ship 数字员工 templates that depend on it: its tools, pages and data. They are
+installed with the plugin and appear in the template catalog while the plugin is installed and
+enabled.
+
+## Layout
+
+```
+templates/<key>/
+├── template.config.json   # everything except the workspace documents; `agents` for experts (main first)
+├── workspace/*.md         # the main agent's root files: IDENTITY, SOUL, AGENTS, TOOLS, …
+├── workspace/<dir>/…      # other workspace files, shipped under their path
+├── experts/<id>/*.md      # one folder per expert, matching `agents`
+└── avatar.png
+```
+
+Declare each template in `tego.plugin.json`:
+
+```json
+"agentTemplates": [
+  { "key": "notes-assistant", "entry": "templates/notes-assistant/template.json", "icon": "templates/notes-assistant/avatar.png" }
+]
+```
+
+`template.json` is a build output: `tego-plugin-pack` rebuilds it before packing, and
+`tego-plugin-pack templates` rebuilds it when only documents changed. Commit it for review; never
+write your own build script.
+
+## Versions (TP-TPL-001)
+
+Employees created from a template keep a copy. They only see changes through "check template
+updates", which compares by `version`. Raise `version` in `template.config.json` whenever the
+content, `usageGuide` or `quickPrompts` change; doctor reports a changed template whose version
+did not move.
+
+## Usage guide and quick prompts (TP-TPL-002)
+
+- `content.usageGuide.summary`: at most 30 characters, saying what the employee does for the user.
+- `content.usageGuide.setup`: only items the host can check (`envVar`, `knowledgeBase`, `plugin`).
+  Business readiness (a sales target, a bound person) comes from the manifest's
+  `agentReadiness: { "path": "…" }`, answered by your backend for the current user.
+- `content.quickPrompts`: 3–4 prompts a user can click, each with a unique `key`; `requires` may
+  name a `setup[].id` or `plugin:<pluginId>:<itemId>`.
+- In a multi-user tenant the conversation guidance goes into `workspace/AGENTS.md`, not a
+  `BOOTSTRAP.md` ritual.
+
+## Retiring a template
+
+Remove it from `agentTemplates` and publish a new version; the platform archives it. Never write a
+data migration for templates.

package/agent/guides/backend.md

@@ -73,4 +73,12 @@ export const backend = definePluginBackend({
   (`createMaintenance` from `@tego/plugin-sdk/server-runtime`).
 - Outbound HTTP only to hosts in `parts.backend.egress`.
 
+## Running it locally
+
+`pnpm dev` (`tego-plugin dev`) runs this backend for real — built with source maps, started with
+`node`, restarted on every save — against the PostgreSQL in `DATABASE_URL`; only the tego-os host API
+and the gateway's identity are stand-ins (unsupported host calls answer 501). Without a database the
+preview refuses to start, so never "fix" a 503 or a missing permission in the frontend: the backend is
+not running. Read its `[backend]` lines in the output first; `pnpm dev -- --inspect` attaches a debugger.
+
 See storage.md for files and access.md for permissions.

package/agent/guides/host-api-versions.md

@@ -28,6 +28,9 @@ and upload refuses a manifest field newer than the range (TP-MAN-001), as does d
 | 1.33.0          | `workDelegation`                                                                 |
 | 1.34.0          | `attention.request`                                                              |
 | 1.37.0          | `ctx.platform`, `ctx.openExternal`, `ctx.download`, `ctx.copyText`               |
+| 1.38.0          | decision cards (`DecisionCardBlock`, `DecisionCardSurface`)                      |
+| 1.39.0          | `sources.latestUserMessage`, needs `messages.latest_user`                        |
+| 1.40.0          | `recipientUserId` on `attention.get`                                             |
 
 Optional members (`ctx.office`, `ctx.ai`, `ctx.delegation`, `ctx.download` before 1.37) must be
 feature-detected when the range admits an older shell. The full API is in

package/agent/reference/plugin-sdk-api.md

@@ -309,6 +309,7 @@ await ctx.office?.open({
 | API                              | 输入                                         | 返回值与约束                                                                                |
 | -------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `host.sources?.read(id, actor)`  | `actor: { userId, avatarId, metadataOnly? }` | `{ source: unknown }`；宿主复核来源归属、源数据是否存在、捕获授权                           |
+| `host.sources?.latestUserMessage(input)` | `{ topicId, userId, avatarId }`，需在 manifest 声明 `messages.latest_user` | `{ message: { id, topicId, origin, content, createdAt } \| null }`；只返回此人在该话题的最新一条。`origin` 由宿主写入，只有 `typed`、`voice` 是本人原话，其他值或 `null` 都不是；超过 200 字时 `content` 为空 |
 | `host.delegations?.list(userId)` | 用户 ID                                      | `{ delegations: [{ avatarId, enabled, actions }] }`；当前安装的工作委托，用于转交工作前复核 |
 
 `sources.read` 读取平台已授权捕获的来源，不是任意会话查询接口。`delegations.list` 只查询，不能创建或扩张委托；来源捕获、会话绑定和委托管理的其他平台 REST 接口不在 `PluginHostApi` 方法列表中。