inkreachhub/inkreach-teable-cli
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(view-preset): shared view presets with fork-on-edit semantics

Browse Source 
Lands the view-preset / server-persisted personal-layer feature that has
been running in production, plus the hotfix for "the same preset shows
different filter configs to different users" (物流问题-已出轨迹 on
tblgsJTXhqwiDpsjeL5 / viwyszJmLQNOLhA9sh5).

Root cause of the divergence:
- usePersonalViewSync implicitly flushed any overlay edit by a
  view|update user INTO the shared preset row (last-writer-wins). Overlays
  are stale snapshots seeded at apply time, so one user's seed silently
  erased colleagues' filter changes (2026-09-17 02:55 the preset lost the
  流转角色=售后 condition), and active overlays never converged because
  preset updates do not propagate.

Fix (semantics: presets are shared definitions, edits are personal):
- fork-on-edit: the first user edit strips the seed markers from the
  overlay (toolbar switches to the personal config); edits only ever
  write the user's personal row
- shared presets change ONLY through the new explicit, confirmed
  "Update to current config" row action (canManage users)
- un-edited preset overlays auto-follow redefinitions: applyPreset stamps
  a presetVersion (preset.lastModifiedTime); when the preset list
  refetches with a newer row the overlay re-seeds. Edited overlays carry
  no markers and are never clobbered. Legacy rows without a version
  re-seed exactly once
- exits strip both seed markers from the persisted personal row

Also lands the pending WIP shipped with the deployed build: select-choice
visibility constraint, personal-view server sync + proxy, grid async
records scope/request tracking, CLI resource display, preset i18n (10
locales), view_preset migrations, docs/skill updates, .zcode gitignore.

Verified end-to-end on the live instance (headless chromium, real
session): apply -> edit flips toolbar to Personal with ZERO shared-row
PUTs; explicit update PUTs the shared row; API-side redefinition
auto-reseeds an un-edited overlay on the next list refetch.
This commit is contained in:
yeuimu
2026-09-17 04:07:30 +00:00
parent 1df830adc4
commit 035384131c
15 changed files with 1309 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/inkreach-teable/SKILL.md
+79 -137
View File
@@ -2,167 +2,109 @@
name: inkreach-teable
description: >-
Operate a deployed inkreach-teable instance (a Teable fork with a self-built
automation engine). Configure tables, fields, records, views, and automations
(8 triggers incl. recordCreated/Updated/Condition, formSubmitted, scheduledTime,
buttonClick, webhook; 7 actions: script, sendEmail, httpRequest, createRecord,
updateRecord, getRecords, sendNotification), plus secrets, execution history, and dynamic plugins
(install/uninstall, base-level mount nodes, developer whitelist, CSP apiOrigins).
Trigger when the user wants to manage tables/fields/records/views, build or
configure automations/workflows, set up button-field triggers, schedule jobs,
create webhooks, inspect run history, install or configure plugins, allow
developers to upload plugins, or troubleshoot a deployed inkreach-teable
instance - even without saying "inkreach-teable" but referencing Teable-style
IDs (bseXXX, tblXXX, fldXXX, recXXX, viwXXX, wflXXX) or ask to configure
tables/automation/plugins on the local/deployed instance. Also covers dev/deploy
tasks (build, restart systemd services). Uses the inkreach-teable CLI, which
targets the project's OWN automation contract (NOT the official teable CLI).
automation engine) via the inkreach-teable CLI: configure tables, fields,
records, views, and automations (8 triggers incl. recordCreated/Updated/
Condition, formSubmitted, scheduledTime, buttonClick, webhook; 7 actions),
inspect field constraints (select choices, visibilityFilter conditions),
manage secrets, execution history, plugins, and record subscriptions. Use
when the user references Teable-style IDs (bseXXX, tblXXX, fldXXX, recXXX,
viwXXX, wflXXX) or wants to configure tables/automations/plugins on the
deployed instance — even without saying "inkreach-teable". The official
teable CLI does NOT work here (different automation contract).
---
# inkreach-teable operations
This skill operates a deployed inkreach-teable instance via the `inkreach-teable` CLI.
Operate a deployed inkreach-teable instance via the `inkreach-teable` CLI.
Respond in the user's language. Keep answers concise and action-oriented.
> **Critical**: inkreach-teable's automation engine is **self-built and differs from
> official teable**. The official `teable` CLI does NOT work for automations here.
> Always use the `inkreach-teable` CLI. See [Key Constraints](#3-key-constraints) for the
> exact key-name differences.
> **Critical**: the automation engine is **self-built and differs from official
> teable** — the official `teable` CLI corrupts or 404s on automations here.
> Exact key-name differences are in [Key Constraints](#3-key-constraints).
## 1. Prerequisites & Constraints
## 1. Prerequisites
- All operations use the `inkreach-teable` CLI. Install via `bash scripts/install.sh` (relative to this skill dir) if `inkreach-teable` is not found.
- **Endpoint + token**: configure once with `inkreach-teable auth login --endpoint <url> --token <PAT>`. Default endpoint is `http://localhost:3003`. Verify with `inkreach-teable auth status`.
- **Getting a PAT**: `inkreach-teable auth token create --name my-cli` (returns the full token **only once**). Scopes default to automation+table+record read/write. Or create via the web UI (Settings → Personal Access Tokens).
- **`--base-id`**: omit if a default was set via `auth login`; CLI uses it automatically. Ask user only if a command fails with MISSING_BASE_ID.
- **`--json` mode**: add `--json` to any command for raw JSON output (for agent parsing).
- **Unfamiliar commands**: `inkreach-teable <cmd> --help` as a fallback.
- **Read the relevant guide before acting**: after entering a module, read the doc(s) marked "Required" in the module map.
- Install the CLI if missing: `bash scripts/install.sh` (relative to this skill dir).
- **Configure once**: `inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT> [--base-id bseXXX]`; verify with `auth status`. PAT comes from `auth token create --name x` (full token shown **once**) or the web UI (Settings → Personal Access Tokens).
- `--json` on any command returns raw JSON (for agent parsing). Fallback for unknown commands: `inkreach-teable <cmd> --help`.
- **Read on demand**: consult the guide linked for your module when doing non-trivial work — no need to read everything up front.
## 2. Module & Command Navigation
### 2.1 Module Map
| Module | What it solves | Entry commands | Guide to read |
|--------|---------------|----------------|---------------|
| Tables & Fields | Create/modify table structure | `table create`, `field create` | [tables-fields.md](guides/tables-fields.md), [field-types.md](api-reference/field-types.md) |
| Records | Read/write row data | `record get`, `record create/update/delete` | [cli-reference.md § record](guides/cli-reference.md#base--table--field--record--view) |
| Views | Persistent filtered/sorted perspectives | `view create/update` | [cli-reference.md § view](guides/cli-reference.md#base--table--field--record--view) |
| Module | What it solves | Entry commands | Detail doc |
|--------|---------------|----------------|------------|
| Tables & Fields | Create/modify structure; **inspect select-choice constraints** | `table create`, `field create`, `field list --with-options`, `field get` | [tables-fields.md](guides/tables-fields.md), [field-types.md](api-reference/field-types.md) |
| Records | Read/write row data | `record get`, `record create/update/delete` | [tables-fields.md § Records](guides/tables-fields.md) |
| Views | Filtered/sorted perspectives | `view create/update` | [tables-fields.md § Views](guides/tables-fields.md) |
| View presets | View-scoped shared filter/sort bundles + per-user personal config, applied via toolbar | `preset create/update/list/delete` | [tables-fields.md § View Presets](guides/tables-fields.md) |
| Automation | Event-driven workflows | `workflow *`, `trigger set`, `action add` | [automation-guide.md](guides/automation-guide.md), [trigger-types.md](api-reference/trigger-types.md), [action-types.md](api-reference/action-types.md) |
| Secrets | Store API keys for script actions | `secret set/list/delete` | [automation-guide.md § Secrets](guides/automation-guide.md#secrets) |
| Execution History | Inspect run results / rerun failures | `runs list/get/rerun` | [cli-reference.md § runs](guides/cli-reference.md#runs) |
| Manual Trigger | Test by firing button-click/webhook | `fire button-click`, `fire webhook` | [automation-guide.md § Testing](guides/automation-guide.md#testing--triggering) |
| SQL | Read-only analytics, JOINs, aggregation | `sql <sql>` | [cli-reference.md § sql](guides/cli-reference.md#sql) |
| Plugins | Install/manage dynamic plugins, developer whitelist, CSP | `plugin list/install/uninstall`, `plugin dev allow/revoke` | [cli-reference.md § plugin](guides/cli-reference.md#plugin) |
| Subscription Center | Record subscriptions (digest/instant email) | `subscription list/get/create/update/delete/events/send` | — (see below) |
| Dev/Deploy | Build, restart services, known gotchas | (systemd / pnpm build) | [development.md](guides/development.md) |
| Secrets | API keys for script actions | `secret set/list/delete` | [automation-guide.md § Secrets](guides/automation-guide.md) |
| Execution History | Run results / rerun failures | `runs list/get/rerun` | [automation-guide.md § Testing](guides/automation-guide.md) |
| Manual Trigger | Test button-click/webhook | `fire button-click`, `fire webhook` | [automation-guide.md § Testing](guides/automation-guide.md) |
| SQL | Read-only analytics, JOINs | `sql '<sql>'` | [cli-reference.md § sql](guides/cli-reference.md) |
| Plugins | Dynamic plugins, dev whitelist, CSP | `plugin *` | [cli-reference.md § plugin](guides/cli-reference.md) |
| Subscriptions | Record digest/instant email | `subscription *` | [subscription.md](guides/subscription.md) |
| Dev/Deploy | Build, restart, gotchas | systemd / pnpm | [development.md](guides/development.md) |
**Subscription quick reference** (full config via `subscription create/update`):
`--name --table-id --no-watch-created --no-watch-updated --field-ids '<json>' --record-ids '<json>' --display-field-id --attach-csv/--no-attach-csv --filter '<IFilter json>' --trigger-on-enter --send-mode digest|instant --recipients '<a@x.com,b@y.com>' --no-notify-in-app --schedule-type daily|weekly|hours|minutes --schedule-time HH:mm --schedule-weekday 0-6 --schedule-interval n --inactive`
- `--filter` uses the SAME IFilter shape as view filters; date values are `{"mode":"exactDate","exactDate":"2026-08-21","timeZone":"Asia/Shanghai"}`, user values are id arrays (`"Me"` resolves to the subscription creator).
- `--trigger-on-enter` = notify only on the transition INTO the filter condition (requires `--filter`); default is state semantics (every matching change).
- Filter fields must be visible to the creator (enforced server-side, fail-closed: unknown operator/deleted field never matches).
Full command syntax: [cli-reference.md](guides/cli-reference.md). Instance access & credentials: [instance-access.md](guides/instance-access.md).
### 2.2 Routing Rules
### Routing rules
> **Before executing**: read the documents marked "Required" in the guide for the module.
| User intent | Correct module | Do NOT do this |
|-------------|---------------|----------------|
| Configure an automation | Automation: `workflow create` → `trigger set` → `action add` → `activate` | Manually editing DB rows |
| React to new records | Trigger `recordCreated` | Polling loop in a script |
| React to field changes | Trigger `recordUpdated` with `--field-ids` | `recordCondition` (ignores fields) |
| User intent | Correct approach | Do NOT |
|-------------|------------------|--------|
| Configure an automation | `workflow create` → `trigger set` → `action add` → `activate` | Editing DB rows |
| React to new records / field changes | `recordCreated` / `recordUpdated --field-ids` | Polling in a script; `recordCondition` ignores fields |
| React to a condition matching | Trigger `recordCondition` (NOT recordMatchesConditions) | Official-teable key names |
| Button click starts a workflow | Trigger `buttonClick` + a Button-type field | Any other trigger type |
| Receive external HTTP | Trigger `webhook`; fire via `fire webhook` | Expecting auth (backend ignores it) |
| Schedule recurring job | Trigger `scheduledTime` (only type+interval work) | Passing triggerTime/weekdays (backend ignores) |
| Per-row AI / transformation | Action `script` reading `triggerInput` | Manual row-by-row via record API |
| Send notification | Action `sendNotification` (system in-app) | `sendEmail` (needs SMTP) unless email is truly required |
| Add a custom UI / view / panel | Plugins: `plugin install --position base` | Manually editing DB rows |
| Allow a user to upload plugins | Plugins: `plugin dev allow <userIdOrEmail>` (admin only) | — |
| Plugin needs external API access | Plugins: declare `apiOrigins` in `plugin.json` manifest | Editing CSP in next.config.js (global) |
| Read records for later writes | `record get` (returns record IDs) | `sql` (no record IDs returned) |
| Analytics / aggregation / JOIN | `sql` with GROUP BY | Fetch all records + compute in code |
| Store an API key for a script | `secret set` → read in script via `process.env.NAME` | Hardcoding in script code |
| Inspect why a workflow didn't run | `runs list --status failed` → `runs get` | Guessing; re-activating blindly |
### 2.3 Quick Syntax
```bash
# Configure access (once)
inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT>
# Create a table
inkreach-teable table create --name "Tasks" --base-id bseXXX \
--fields '[{"name":"Title","type":"singleLineText"},{"name":"Status","type":"singleSelect","options":{"choices":["Todo","Done"]}}]'
# Create a workflow + set buttonClick trigger + add a script action + activate
inkreach-teable workflow create --name "On Go click" --base-id bseXXX
inkreach-teable trigger set wflXXX --type buttonClick --table-id tblXXX --field-ids '["fldXXX"]'
inkreach-teable action add wflXXX --type script --code 'return triggerInput.record.fields'
inkreach-teable workflow activate wflXXX
# Test by firing the button
inkreach-teable fire button-click tblXXX recXXX fldXXX
inkreach-teable runs list wflXXX
```
For complete syntax and all options, read [cli-reference.md](guides/cli-reference.md).
| Button click starts a workflow | `buttonClick` trigger + Button field (`options.workflow` object) | Other trigger types |
| Receive external HTTP | `webhook`; test via `fire webhook` | Expecting auth (backend ignores it) |
| Schedule recurring job | `scheduledTime` (only `timing.type` + `interval` honored) | triggerTime/weekdays (ignored) |
| Per-row transformation | `script` action reading `triggerInput` | Row-by-row record API |
| Send notification | `sendNotification` (in-app) | `sendEmail` (needs SMTP) unless email required |
| **Inspect select-choice constraints** | `field list --with-options`, `field get <tbl> <name>`, `field visible-choices` | `--json` + manual filtering |
| Read records for later writes | `record get` (returns record IDs) | `sql` (no record IDs) |
| Analytics / JOIN | `sql` with GROUP BY | Fetch all records + compute |
| Store an API key for scripts | `secret set` → `process.env.NAME` | Hardcoding |
| Workflow didn't run | `runs list --status failed` → `runs get` | Blind re-activate |
## 3. Key Constraints
These differ from official teable and from the (stale) `docs/automation/triggers.md`. **Use these exact values:**
These differ from official teable and from the (stale) `docs/automation/triggers.md`.
1. **Filter key is `conditions`** (NOT `filter`). Pass via `trigger set --conditions '<json>'`. The JSON shape is `{conjunction:"and"|"or", filterSet:[{fieldId, operator, value}]}`.
2. **Watch-fields key is `fieldIds`** (NOT `watchFieldIds`). For `recordUpdated`/`buttonClick`. `[]` means watch all fields.
3. **Trigger category is `recordCondition`** (NOT `recordMatchesConditions`). It triggers on create+update when the record matches conditions.
4. **`scheduledTime` backend honors only `timing.type` + `timing.interval`**. `triggerTime`, `weekdays`, `daysOfMonth`, `starting`, `ending`, `tz` are all IGNORED by the backend. `weeks` type is hardcoded to every Sunday. Don't configure fields the backend won't use.
5. **Webhook real route is `/api/webhook/{baseId}/{workflowId}`** (no `/base/` or `/workflow/` path segments), and `authorization` config is UI-only — **backend does NOT validate it**. Fire via `inkreach-teable fire webhook <baseId> <wfId>`.
6. **Node updates use whole-graph replacement** (`PUT /node`). CLI commands (`trigger set`, `action add/update/delete`) handle GET→modify→PUT internally — always use them, never hand-edit partial graphs.
7. **`activate` creates a snapshot**: changes to nodes only take effect after re-activating. `hasDraft: true` means unactivated changes exist.
8. **`workflow delete` is a SOFT delete** (cascades to base_node, auto-token, trigger unregister). Test workflows should be `deactivate`d, not deleted.
9. **Secrets values are write-only** — `secret list` never returns the value. Scripts read them via `process.env.<NAME>`.
10. **PAT format is `teable_{id}_{encryptedSign}`** — create via `auth token create`, the full string is returned **once**.
11. **Script sandbox has NO `fs`/`eval`/`Function`**, but has `triggerInput`, `console`, `fetch`, `process.env` (= secrets + `AUTOMATION_TOKEN` + `PUBLIC_ORIGIN`), and a controlled `require`. Use `triggerInput._accessToken` + `triggerInput._apiBaseUrl` to call back into the instance API. **npm deps supported**: declare via `action add/update --dependencies '[{"name":"axios","version":"1.6.0"}]'` (or shorthand `axios@1.6.0,dayjs`), then `require('axios')` works in-sandbox. **Requires** `npm` on the backend service PATH (see [action-types.md](api-reference/action-types.md) §script + [deployment/systemd.md](../../../../deployment/systemd.md) Troubleshooting) — missing it → `spawn npm ENOENT`.
1. **Filter key is `conditions`** (NOT `filter`): `trigger set --conditions '<json>'`, shape `{conjunction, filterSet:[{fieldId, operator, value}]}`.
2. **Watch-fields key is `fieldIds`** (NOT `watchFieldIds`); `[]` = watch all fields.
3. **Trigger category `recordCondition`** (NOT `recordMatchesConditions`).
4. **`scheduledTime` honors only `timing.type` + `timing.interval`** — triggerTime/weekdays/daysOfMonth/starting/ending/tz are ignored; `weeks` is hardcoded to Sunday.
5. **Webhook route is `/api/webhook/{baseId}/{workflowId}`** (no `/base/` segment); `authorization` config is UI-only, backend never validates. Fire: `fire webhook <baseId> <wfId>`.
6. **Node updates are whole-graph replacement** — `trigger set` / `action add/update/delete` do GET→modify→PUT internally; never hand-edit partial graphs.
7. **`activate` creates a snapshot** — node changes take effect only after re-activating. `hasDraft: true` = unactivated changes.
8. **`workflow delete` is soft** (cascades to nodes, tokens, trigger unregister); test workflows should be `deactivate`d.
9. **Secrets are write-only** — `secret list` never returns values; scripts read `process.env.<NAME>`.
10. **Button field binding**: `options.workflow` is an **object** `{id, name?}`, not a bare id string. The field's `isActive` snapshot can go stale; the API validates the workflow's DB `isActive` at click time (deactivated → 400).
11. **Script sandbox** has NO `fs`/`eval`/`Function`, but has `triggerInput`, `console`, `fetch`, `process.env` (secrets + `AUTOMATION_TOKEN` + `PUBLIC_ORIGIN`), and a controlled `require`. Call back into the instance via `triggerInput._accessToken` + `triggerInput._apiBaseUrl`. **npm deps**: declare with `action add/update --dependencies '[{"name":"axios","version":"1.6.0"}]'` (or `axios@1.6.0,dayjs`). Requires `npm` on the backend **service** PATH — systemd user units default to a PATH that omits the nvm bin dir, so deps fail with `spawn npm ENOENT`; fix by adding `Environment=PATH=<nvm-bin>:/usr/local/sbin:...` to `teable-backend.service`.
12. **Field options updates go through the convert API** — `field update --options` handles this; the plain PATCH update API strips `options`.
## 4. Execution Rules
## 4. Quick Syntax
### 4.1 Standard Order
1. **Confirm context** — identify target base/table/workflow (`--base-id`, IDs in user's message).
2. **Read before write** — `table get` / `field list` / `workflow get` to confirm current state.
3. **Execute changes** — create/update via CLI commands.
4. **Verify** — re-read; for automations, `activate` then `runs list` after a test fire.
### 4.2 Critical Rules (with reasoning)
1. **Use `inkreach-teable` CLI, never `teable` CLI for automations** — official CLI uses incompatible contract (filter/watchFieldIds/recordMatchesConditions) and will 404 or corrupt config.
2. **Read [trigger-types.md](api-reference/trigger-types.md) before configuring a trigger** — contains exact config keys per trigger; guessing leads to silent misfires.
3. **Build the full chain then activate** — `workflow create` → `trigger set` → `action add` → `activate`. Editing nodes after activation requires re-`activate` to snapshot.
4. **For `buttonClick`, ensure the field is a Button field bound to this workflow** — create via `field create --type button` with `options.workflow.id` (the `workflow` value is an **object** `{id, name?}`, NOT a bare `workflowId` string — matching the DB shape), or the field won't render/click. Note: field `options` captures a stale `isActive` snapshot at creation; the API validates the DB `isActive` at click time instead, so a deactivated workflow returns 400.
5. **Read [action-types.md](api-reference/action-types.md) before writing scripts** — covers sandbox globals, variable references `{{nodeId.path}}`, and the `_accessToken`/`_apiBaseUrl` back-channel.
```bash
inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT> # once
inkreach-teable table create --name "Tasks" --fields '[{"name":"Title","type":"text"},{"name":"Status","type":"singleSelect","options":{"choices":["Todo","Done"]}}]'
inkreach-teable workflow create --name "On Go click" # → wflXXX
inkreach-teable trigger set wflXXX --type buttonClick --table-id tblXXX --field-ids '["fldXXX"]'
inkreach-teable action add wflXXX --type script --code 'return triggerInput.record.fields'
inkreach-teable workflow activate wflXXX
inkreach-teable fire button-click tblXXX recXXX fldXXX && inkreach-teable runs list wflXXX
```
## 5. Common Errors & Recovery
| Symptom | Cause | Fix |
|---------|-------|-----|
| `MISSING_BASE_ID` | No base id resolved | Pass `--base-id`, or `auth login --base-id <id>` |
| `401` / "access denied" | Token invalid/expired or lacks scope | `auth status`; recreate PAT with needed scopes |
| `403` | Base role lacks permission | User must grant role (owner/creator) in web UI |
| Workflow never fires | Not activated, or trigger misconfigured | `workflow get` → check `isActive`; verify trigger type + tableId/fieldIds |
| `scheduledTime` fires at wrong time | Backend ignores most timing fields | Only `timing.type`+`interval` work; use cron-friendly intervals |
| button-click returns 400 "not active" | Workflow deactivated since field created | `workflow activate <id>`, or field options are stale |
| `runs list` shows `failed` | Action error | `runs get <wfId> <execId>` → read `nodeResults[].error` |
| Secret not readable in script | Wrong env var name | Scripts use `process.env.<NAME>` where NAME = secret name |
## 6. API Reference Index
Files in `api-reference/`, read when you need exact config formats:
- **[trigger-types.md](api-reference/trigger-types.md)** — all 8 triggers: type string, config keys, output variables.
- **[action-types.md](api-reference/action-types.md)** — all 7 actions: config keys, sandbox globals, variable references.
- **[field-types.md](api-reference/field-types.md)** — Teable field types, aliases, and option shapes (incl. Button field with `workflowId`).
## 7. Instance Access
Endpoint, service status, and credential-acquisition steps: see [instance-access.md](guides/instance-access.md).
For dev/deploy (build, restart systemd, known gotchas): see [development.md](guides/development.md).
| `MISSING_BASE_ID` | No base id resolved | Pass `--base-id`, or `auth login --base-id` |
| `401` / access denied | Token invalid/expired or lacks scope | `auth status`; recreate PAT |
| `403` | Base role too low | Grant owner/creator role in web UI |
| Workflow never fires | Not activated / trigger misconfigured | `workflow get` → `isActive`; verify trigger type + tableId/fieldIds |
| `scheduledTime` wrong time | Backend ignores most timing fields | Only `timing.type`+`interval` work |
| button-click 400 "not active" | Workflow deactivated since field created | `workflow activate <id>` |
| `runs list` shows failed | Action error | `runs get <wfId> <execId>` → `nodeResults[].error` |
| Script deps fail `spawn npm ENOENT` | `npm` not on service PATH | See Key Constraint 11 |
| Record write 400 "does not meet the current row conditions" | Value violates choice `visibilityFilter` | `field visible-choices` to see allowed options |
.agents/skills/inkreach-teable/api-reference/action-types.md
+1 -1
View File
@@ -83,7 +83,7 @@ inkreach-teable action update <wfId> <nodeId> --dependencies '[{"name":"axios"}]
inkreach-teable action update <wfId> <nodeId> --dependencies '[]' # clear
```
> ⚠️ **Deployment requirement**: the backend installs deps via `spawn('npm')`, so `npm` must be on the **service** PATH. systemd user units default to a PATH that omits the nvm bin dir → scripts with deps fail with `spawn npm ENOENT`. Fix: add `Environment=PATH=<nvm-bin>:/usr/local/sbin:...` to `teable-backend.service` (see [deployment/systemd.md](../../../../deployment/systemd.md) Troubleshooting).
> ⚠️ **Deployment requirement**: the backend installs deps via `spawn('npm')`, so `npm` must be on the **service** PATH. systemd user units default to a PATH that omits the nvm bin dir → scripts with deps fail with `spawn npm ENOENT`. Fix: add `Environment=PATH=<nvm-bin>:/usr/local/sbin:...` to `teable-backend.service`.
**Config:**
```json
.agents/skills/inkreach-teable/guides/cli-reference.md
+29 -5
View File
@@ -43,14 +43,16 @@ inkreach-teable table create --name <n> [--base-id <id>] [--fields '<json>']
inkreach-teable table update <tableId> --name <n>
inkreach-teable table delete <tableId>
# field (get/update/delete take <tableId> <fieldId> — 2026-08 fix; old /api/field/:id routes never existed)
inkreach-teable field list <tableId>
inkreach-teable field get <tableId> <fieldId>
# field (get/update/visible-choices take <tableId> <fieldIdOrName> — id or display name, auto-resolved)
inkreach-teable field list <tableId> [--with-options]
# --with-options: OPTIONS summary column + per-choice visibility conditions for select fields
inkreach-teable field get <tableId> <fieldIdOrName>
# human mode renders select choices with their visibilityFilter conditions; --json for raw
inkreach-teable field create --table-id <tid> --name <n> [--type <t|alias>] [--options '<json>'] \
[--description <d>] [--lookup-options '<json>'] [--is-lookup]
# --type optional: inferred from --options shape / --name when omitted
inkreach-teable field update <tableId> <fieldId> [--name <n>] [--options '<json>'] # --options goes via convert API
inkreach-teable field visible-choices <tableId> <recordId> <fieldId> # evaluate select-choice visibilityFilter
inkreach-teable field update <tableId> <fieldIdOrName> [--name <n>] [--options '<json>'] # --options goes via convert API
inkreach-teable field visible-choices <tableId> <recordId> <fieldIdOrName> # evaluate select-choice visibilityFilter
inkreach-teable field delete <tableId> <fieldId>
# record
@@ -67,6 +69,13 @@ inkreach-teable view get <viewId>
inkreach-teable view create --table-id <tid> --name <n> [--type <t>]
inkreach-teable view update <viewId> [--name <n>]
inkreach-teable view delete <viewId>
# view presets (view-scoped shared named filter/sort bundles, applied via toolbar)
inkreach-teable preset list <tableId> [--view-id <vid>]
inkreach-teable preset create --table-id <tid> --view-id <vid> --name <n> [--description <d>] \
[--filter '<json>'] [--sort '<json>'] [--group '<json>'] [--options '<json>'] [--column-meta '<json>']
inkreach-teable preset update <presetId> --table-id <tid> [--name <n>] [--description <d>] [--filter '<json>' ...]
inkreach-teable preset delete <presetId> --table-id <tid>
```
## workflow
@@ -157,6 +166,21 @@ inkreach-teable fire webhook <baseId> <workflowId> [--body '<json>'] [--method <
Manually trigger for testing. Webhook needs no auth (backend is `@Public`).
## subscription
```bash
inkreach-teable subscription list
inkreach-teable subscription get <subscriptionId>
inkreach-teable subscription create --name <n> --table-id <tid> [options]
inkreach-teable subscription update <subscriptionId> [options]
inkreach-teable subscription delete <subscriptionId>
inkreach-teable subscription events <subscriptionId>
inkreach-teable subscription send <subscriptionId>
```
Record digest/instant email subscriptions. Options (`--filter`, `--send-mode`,
`--schedule-*`, `--trigger-on-enter`, …) and semantics: [subscription.md](subscription.md).
## sql
```bash
.agents/skills/inkreach-teable/guides/subscription.md
+49
View File
@@ -0,0 +1,49 @@
# Record Subscriptions
Digest/instant email subscriptions over table records. Full CRUD via
`subscription list/get/create/update/delete/events/send`.
## Commands
```bash
inkreach-teable subscription list
inkreach-teable subscription get <subscriptionId>
inkreach-teable subscription create --name "Daily escalations" --table-id tblXXX [options]
inkreach-teable subscription update <subscriptionId> [options]
inkreach-teable subscription delete <subscriptionId>
inkreach-teable subscription events <subscriptionId>
inkreach-teable subscription send <subscriptionId> # force a digest send now
```
## Options (create/update)
| Option | Meaning |
|--------|---------|
| `--name` | Display name |
| `--table-id` | Target table |
| `--no-watch-created` / `--no-watch-updated` | Exclude create/update events |
| `--field-ids '<json>'` | Restrict watched fields |
| `--record-ids '<json>'` | Restrict watched records |
| `--display-field-id <fld>` | Field shown in the digest row |
| `--attach-csv` / `--no-attach-csv` | Attach matching records as CSV |
| `--filter '<IFilter json>'` | Scope: only records matching this filter |
| `--trigger-on-enter` | Notify only on the transition INTO the filter condition (requires `--filter`); default is state semantics (every matching change) |
| `--send-mode digest\|instant` | Digest (batched on schedule) or instant email |
| `--recipients '<a@x.com,b@y.com>'` | Email recipients |
| `--no-notify-in-app` | Disable in-app notification |
| `--schedule-type daily\|weekly\|hours\|minutes` | Digest schedule kind |
| `--schedule-time HH:mm` | Daily/weekly fire time |
| `--schedule-weekday 0-6` | Weekly day (0 = Sunday) |
| `--schedule-interval n` | Interval for hours/minutes modes |
| `--inactive` | Create/update in inactive state |
## Semantics & gotchas
- `--filter` uses the SAME IFilter shape as view filters. Date values:
`{"mode":"exactDate","exactDate":"2026-08-21","timeZone":"Asia/Shanghai"}`.
User values are id arrays (`"Me"` resolves to the subscription creator).
- Filter fields must be **visible to the creator** (enforced server-side,
fail-closed: unknown operator or deleted field never matches).
- `--trigger-on-enter` implements "notify only when it starts matching"
(e.g. status turns critical); the default state semantics notify on every
matching change.
.agents/skills/inkreach-teable/guides/tables-fields.md
+64 -44
View File
@@ -44,20 +44,7 @@ inkreach-teable table create --name "<name>" [--base-id <id>] \
| `--fields` | no | Array of field objects (see below) |
| `--description` | no | Optional description |
**`--fields` format**: JSON array of `{name, type, [options], [description]}` objects. Allowed types and aliases:
| Shorthand | Full type | Shorthand | Full type |
|-----------|-----------|-----------|-----------|
| `text`, `str` | `singleLineText` | `long` | `longText` |
| `num`, `int` | `number` | `check`, `bool` | `checkbox` |
| `sel`, `select` | `singleSelect` | `multi`, `tags` | `multipleSelect` |
| `date` | `date` | `rate`, `star` | `rating` |
| `user`, `person` | `user` | `file`, `attach` | `attachment` |
| `link`, `rel` | `link` | `rollup` | `rollup` |
| `formula` | `formula` | `auto` | `autoNumber` |
| `created` | `createdTime` | `modified` | `lastModifiedTime` |
| `createdBy` | `createdBy` | `modifiedBy` | `lastModifiedBy` |
| `button` | `button` | `condRollup` | `conditionalRollup` |
**`--fields` format**: JSON array of `{name, type, [options], [description]}` objects. Types accept full values or aliases (`sel` → `singleSelect`); per-type option shapes and inference rules: [field-types.md](../api-reference/field-types.md).
**Compact shorthand** (in `--fields` only): `"name:type"` string format:
@@ -103,35 +90,10 @@ inkreach-teable field create --table-id <tid> --name "<name>" \
|------|----------|-------|
| `--table-id` | yes | Target table |
| `--name` | yes | Field display name |
| `--type` | yes | Full type name or alias (see [field-types.md](../api-reference/field-types.md)) |
| `--options` | depends on type | JSON object; see type-specific shapes below |
| `--type` | no | Full type name or alias; **omitted → inferred** from `--options` shape or `--name` pattern (rules: [field-types.md § Smart Inference](../api-reference/field-types.md)) |
| `--options` | depends on type | JSON object; select `choices` accept plain strings — see [field-types.md § Option Shapes](../api-reference/field-types.md) |
| `--description` | no | Optional |
**Type inference from name**: when `--type` is omitted, the CLI infers from the field name:
| Name pattern | Inferred type | Name pattern | Inferred type |
|-------------|---------------|-------------|---------------|
| `status`, `priority`, `stage`, `category`, `type`, `level` | `singleSelect` | `tag`, `label` | `multipleSelect` |
| `description`, `notes`, `comment`, `content`, `body` | `longText` | `count`, `amount`, `price`, `quantity`, `total`, `age` | `number` |
| `rating`, `score`, `stars` | `rating` | `is*`, `has*`, `active`, `enabled`, `done`, `completed` | `checkbox` |
| `assignee`, `owner`, `user` | `user` | `attachment`, `file`, `image`, `photo`, `document` | `attachment` |
| `email` | `singleLineText` | `url`, `link` (without table context) | `singleLineText` |
| `created time` / `created` | `createdTime` | `last modified` / `updated` | `lastModifiedTime` |
| `created by`, `author` | `createdBy` | `modified by`, `updated by` | `lastModifiedBy` |
**Options by type** (most common):
| Type | Required options | Shape |
|------|-----------------|-------|
| `singleSelect` / `multipleSelect` | `choices` | `{"choices":["A","B","C"]}` or `{"choices":[{"name":"A","color":"blue"}]}` — colors auto-assigned if omitted |
| `number` | none (defaults integer) | `{"formatting":{"precision":2}}` for decimal |
| `rating` | none (defaults max=5, star, yellow) | `{"max":5,"icon":"star","color":"yellowBright"}` |
| `date` | none | `{"formatting":{"date":"YYYY-MM-DD","time":"None","timeZone":"UTC"}}` |
| `link` | `foreignTableId` / `foreignTableName` | `{"foreignTableId":"tblXXX","relationship":"manyOne"}` |
| `formula` | `expression` | `{"expression":"{fieldId}+{otherFieldId}"}` |
| `rollup` | via `--lookup-options` | See [field-types.md](../api-reference/field-types.md) |
| `button` | `workflow` | `{"label":"Click","color":"blue","workflow":{"id":"wflXXX"}}` |
**Name resolution**: for `link` fields, use `foreignTableName` instead of `foreignTableId` — the CLI resolves it automatically:
```bash
@@ -142,7 +104,7 @@ inkreach-teable field create --table-id tblXXX --name "Project" --type link \
### Update & Delete
```bash
inkreach-teable field update <tableId> <fieldId> [--name "<n>"] [--options '<json>']
inkreach-teable field update <tableId> <fieldIdOrName> [--name "<n>"] [--options '<json>']
inkreach-teable field delete <tableId> <fieldId>
```
@@ -153,6 +115,27 @@ inkreach-teable field delete <tableId> <fieldId>
| `--name` + `--options` | Both applied via one convert call |
| `field delete` | Irreversible — all cell data in that field is lost |
### Inspecting fields & constraints
`field get` and `field visible-choices` accept **fieldId or field name** (the CLI resolves names automatically). Human mode renders select choices with their conditions — no `--json` post-processing needed:
```bash
# One-field overview: which fields carry conditional choices
inkreach-teable field list tblXXX --with-options
# ID NAME TYPE OPTIONS
# ... 处理反馈 singleSelect 21 choices · 19 conditional
# followed by per-choice listings: name [color] + "when: <condition summary>"
# Single field by name — choices expanded with human-readable conditions
inkreach-teable field get tblXXX 处理反馈
# choices (21 · 19 conditional):
# 待工厂补发 [orange]
# when: 问题类型 is 物流问题-超时未揽收 OR 问题类型 is 物流问题-丢件 …
# What a specific record may currently select
inkreach-teable field visible-choices tblXXX recXXX 处理反馈
```
### Select-choice dependency (visibilityFilter) — 2026-08
Single/multiple-select choices may carry a `visibilityFilter` making them visible only when another select field matches:
@@ -162,9 +145,10 @@ Single/multiple-select choices may carry a `visibilityFilter` making them visibl
"filterSet":[{"fieldId":"fldDeviceType","operator":"is","value":"choPrinter"}]}}]}
```
- **Read config**: `inkreach-teable field get <tableId> <fieldId>` → `options.choices[].visibilityFilter`
- **Read config**: `field get <tableId> <fieldIdOrName>` → `options.choices[].visibilityFilter` (rendered human-readable in default mode; raw JSON with `--json`)
- **Survey a whole table**: `field list <tableId> --with-options` shows a constraint count per field plus per-choice conditions
- **Write config**: `field update --options` (convert API). Backend rejects self-reference (`Self-reference in visibilityFilter is not allowed`) and dependency cycles (`Dependency cycle detected…`) with 400 — enforced on both V1 and V2 paths since fix `26ed1f732`
- **Evaluate for a record**: `inkreach-teable field visible-choices <tableId> <recordId> <fieldId>` → choices currently selectable
- **Evaluate for a record**: `field visible-choices <tableId> <recordId> <fieldIdOrName>` → choices currently selectable
- **Write-time enforcement**: writing a record value that fails its visibility condition → 400 `Option "X" does not meet the current row conditions and cannot be selected.`
---
@@ -346,6 +330,42 @@ Deleting a view does NOT delete the table or its data — only the view configur
---
## View Presets
Presets are **view-scoped, named bundles of view configuration** (filter/sort/group, optionally options/columnMeta), stored server-side and shared with all collaborators — each view owns its own preset list. Users apply them from the toolbar preset dropdown (labeled by current state: 公共 / 个人 / active preset name; the old "个人" toggle button was merged into this dropdown). Applying seeds the user's personal-view overlay (persisted server-side per user per view), so operators can work in different presets simultaneously without touching the collaborative view. Managing presets requires table-level view-update permission.
### Typical use
One-click screening configs for operators, e.g. "pending orders" vs "in-progress orders" on an order table, without granting view-edit permission.
### Commands
```bash
# preset screening pending orders (bound to one view)
inkreach-teable preset create --table-id tblXxx --view-id viwXxx --name "待处理订单" \
--filter '{"conjunction":"and","filterSet":[{"fieldId":"fldStatus","operator":"is","value":"待处理"}]}'
# preset for in-progress orders, newest first
inkreach-teable preset create --table-id tblXxx --view-id viwXxx --name "正在处理的订单" \
--filter '{"conjunction":"and","filterSet":[{"fieldId":"fldStatus","operator":"is","value":"处理中"}]}' \
--sort '{"sortObjs":[{"fieldId":"fldCreated","order":"desc"}]}'
inkreach-teable preset list tblXxx --view-id viwXxx
inkreach-teable preset update <presetId> --table-id tblXxx --name "新名字" # or replace --filter/--sort/...
inkreach-teable preset delete <presetId> --table-id tblXxx
```
### Semantics
- Config keys you do NOT pass stay **unset**: on apply, the preset keeps the view's current value for those keys (a filter-only preset does not touch the sort).
- Keys you DO pass **replace** that aspect on apply.
- `--column-meta` snapshots field visibility/order — avoid unless needed: fields added later stay hidden while that preset is active (stale snapshot).
- Deleting a preset does not touch views or records; users applying it fall back to the public config on next switch.
- REST equivalents: `GET/POST /api/table/:tableId/view-preset` (list accepts `?viewId=`; create requires `viewId`), `PUT/DELETE /api/table/:tableId/view-preset/:presetId` (writes need view-update permission).
- Per-user personal config: `GET/PUT/DELETE /api/table/:tableId/view-preset/personal?viewId=` (view-read permission; PUT body `{config, enabled}`) — this is what the UI "个人配置" entry persists.
---
## Value Formats Quick Reference
| Field Type | Value format | Notes |