feat(cli): record 写入 --typecast/--order/--field-key-type + 附件字段 URL 导入 skill 文档 (0.2.0)

2026-10-14 00:21:00 +00:00
parent a3fa01e25f
commit 4462475a6f
9 changed files with 206 additions and 18 deletions
@@ -61,6 +61,7 @@ Full command syntax: [cli-reference.md](guides/cli-reference.md). Instance acces
 | **Inspect select-choice constraints** | `field list --with-options`, `field get <tbl> <name>`, `field visible-choices` | `--json` + manual filtering |
 | **Write a select-field value** | Verify the value exists in choices first (`field list --with-options`); need a new value → `field update --options` to add the choice, then write | Blind `record update` (400, or typecast silently resolves to null / mutationApplied=false — it never creates choices) |
 | Read records for later writes | `record get` / `record list` (returns record IDs) | Official-teable SQL APIs (none here) |
+| **Attach a remote file to a record** | `record create/update --fields '{"Files":[{"url":"https://…"}]}'` (backend downloads & stores it) | The multipart `uploadAttachment` route or manual signature/notify upload (only needed for local files) |
 | Analytics / aggregation | `record get --filter` + compute, script action, or grouped grid view | `sql` — this deployment has NO SQL query API (CLI 0.1.5 removed the dead command) |
 | 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 |
@@ -90,6 +91,7 @@ These differ from official teable and from the (stale) `docs/automation/triggers
 inkreach-teable auth login --endpoint https://table.inkreach.cc --token <PAT>   # once
 inkreach-teable table create --name "Tasks" --fields '[{"name":"Title","type":"text"},{"name":"Status","type":"singleSelect","options":{"choices":["Todo","Done"]}}]'
 inkreach-teable record create --table-id tblXXX --fields '{"Title":"a"}'   # 单条;批量用 --records '[{"fields":{...}}]'
+inkreach-teable record create --table-id tblXXX --fields '{"Files":[{"url":"https://…/f.png"}]}'  # 附件字段直接吃 URL(服务端下载入库);字符串形式加 --typecast
 inkreach-teable record list --table-id tblXXX [--filter '<json>']          # 查询/分页(= record get)
 inkreach-teable record delete --table-id tblXXX recXXX [recYYY ...]       # 也可 --record-ids 'recA,recB'
 inkreach-teable workflow create --name "On Go click"      # → wflXXX
@@ -21,8 +21,7 @@ Complete reference of all Teable field types, aliases, option shapes, and smart
 | `date` | Date | Date or datetime | No |
 | `checkbox` | Checkbox | Yes/no toggle | No |
 | `rating` | Rating | Star/numeric rating 1..10 | No (defaults: max=5, star, yellow) |
-| `attachment` | Attachment | Files, images, documents | No |
-| `user` | User | Person/collaborator reference | No |
+| `attachment` | Attachment | Files, images, documents; cell values also accept `{"url":"https://…"}` items (server downloads the file) | No || `user` | User | Person/collaborator reference | No |
 | `link` | Link | Reference records in another table | Yes (`foreignTableId`/`foreignTableName`) |
 | `lookup` | Lookup | Mirror a field from linked record | Yes (`lookupOptions`) |
 | `rollup` | Rollup | Aggregate linked records (SUM, COUNT, etc.) | Yes (expression + `lookupOptions`) |
@@ -410,6 +409,7 @@ When `--type` is omitted, the CLI infers the type from the field name:
 | `user` | `{"id":"usrXXX","title":"Alice"}` | `"Alice"` or `"alice@example.com"` |
 | `link` (single) | `{"id":"recXXX"}` or `[{"id":"recXXX"}]` | `"Record Display Name"` |
 | `link` (multi) | `[{"id":"recA"},{"id":"recB"}]` | `["Record A","Record B"]` |
+| `attachment` | `[{"url":"https://…/f.png","name":"f.png"}]` (V1 legacy bases: token items only) | `"https://…/f.png"` or `"https://…/a.png,actXXX"` (comma-separated urls/ids) |

 **When to use**: always use `--typecast` when creating/updating records with user or link fields — it eliminates manual ID lookups.

@@ -152,6 +152,16 @@ const res = await fetch(triggerInput._apiBaseUrl + "/api/table/tblB/record", {
   `401` = bad/expired token, `403` = scope or base-role too low.
 6. To see the exact request the CLI sends for any operation, run it with
   `--debug` (prints method/url/body) — the fastest way to learn a route.
+7. **Attachment fields accept URLs** (2026-10): pass `{"url":"https://…","name":"…"}` items
+   (or a URL string with `typecast:true` — note `typecast` is a BODY key) in
+   record create/update `fields`, and the backend downloads the file
+   (SSRF-guarded, size-capped) into attachment storage — response items come
+   back with real `token`/`presignedUrl`. A failed download rejects the whole
+   request (400); nothing is silently dropped. V1 (legacy) bases need
+   `typecast:true` for the string form, V2 bases accept both. The dedicated
+   `POST /api/table/{tid}/record/{rid}/{fid}/uploadAttachment` (multipart,
+   `file` or `fileUrl`) is the older single-record path — the plain record
+   routes now cover URL imports.

 ## 5. Full Route Inventory (this guide ≠ the whole API)

@@ -71,6 +71,8 @@ inkreach-teable record get-one <recordId> --table-id <tid>
 inkreach-teable record create --table-id <tid> --fields '<json>'            # single
 inkreach-teable record create --table-id <tid> --records '<json>'           # batch
 inkreach-teable record update --table-id <tid> --records '<json>'
+# shared write flags: [--typecast] [--field-key-type <name|id|dbFieldName>]
+# [--order '{"viewId":"viwX","anchorId":"recY","position":"before|after"}'] — insert/move in a manual-sort view
 inkreach-teable record delete --table-id <tid> <recordId> [recordId ...]   # or --record-ids <csv>

 # view
@@ -200,10 +202,14 @@ Manage plugins and developer whitelist.
 inkreach-teable plugin list

 # Register a URL-served plugin (runtimeType=url; status published immediately)
-# positions: "base"|"panel"|"view"|"dashboard"|"contextMenu"
+# positions: "base"|"panel"|"view"|"dashboard"|"contextMenu"|"route"
 inkreach-teable plugin register --url <url> --name <name> [--positions '["panel"]'] [--logo <url>] [--description <d>]
-# Bundle (upload) plugins use a different flow — see skill guides/tables-fields.md
-# or api docs: create kebab-id plugin (developer whitelist) → upload → admin publish.
+# Bundle (IIFE upload) plugins use a different flow — use the
+# `inkreach-teable-plugin` skill instead: teable-plugin create/dev/deploy
+# (scaffold → watch+hot-reload dev loop → multi-asset upload with chunks,
+# source maps and css). Since 2026-10: POST /api/plugin (custom kebab-id,
+# plugin_developer whitelist) and upload-bundle both accept PATs, and
+# position "route" renders full-page apps at /base/:baseId/p/:pluginId.

 # Developer whitelist (admin only)
 inkreach-teable plugin dev list
@@ -215,6 +221,8 @@ inkreach-teable plugin install --plugin <pluginId> --name "My Plugin" --position
 #   ⚠️ For view/dashboard-position plugins, run `plugin config enable` BEFORE
 #   install, or the install API returns 403 RESTRICTED_RESOURCE
 #   'Plugin is not enabled for this base'.
+#   position "route" mounts a full-page app at /base/:baseId/p/:pluginId
+#   (no enable gate — the URL is the access point).
 inkreach-teable plugin installs        # list installs in current base
 inkreach-teable plugin uninstall --install <installId>

@@ -251,6 +251,25 @@ inkreach-teable record create --table-id tblXXX --fields '{"Assignee":{"id":"usr
 inkreach-teable record create --table-id tblXXX --fields '{"Assignee":"Alice"}' --typecast
 ```

+**Attachment URL import** (2026-10): attachment fields accept http(s) URLs — the
+backend downloads the file (SSRF-guarded, size-capped) and stores it as a real
+attachment with thumbnail. Two forms:
+
+```bash
+# Object form — works without --typecast; name is optional (derived from the URL)
+inkreach-teable record create --table-id tblXXX \
+  --fields '{"Files":[{"url":"https://example.com/f.png","name":"report.png"}]}'
+
+# String form — needs --typecast; comma-separates URLs and existing actXXX ids
+inkreach-teable record create --table-id tblXXX --typecast \
+  --fields '{"Files":"https://example.com/a.png,https://example.com/b.png"}'
+```
+
+Notes: only `http:`/`https:` URLs; URLs containing commas cannot be expressed in
+the string form (use the object form); a failed download rejects the whole
+request with 400 (nothing is silently dropped); V1 (legacy) bases require
+`--typecast` for the string form, V2 bases accept both forms directly.
+
 **`--records` format** (batch): `{"header":["Field1","Field2"],"records":[["val1","val2"],["val3","val4"]]}`

 ### Update
@@ -261,7 +280,7 @@ inkreach-teable record update --table-id <tid> --records '<json>'

 **`--records` format**: `[{"id":"recXXX","fields":{"FieldName":"newValue"}}]` — array of `{id, fields}` objects. Batch up to 2000.

-**Record reordering**: pass `--order` with `viewId`, `anchorId`, `position`:
+**Record reordering**: pass `--order` with `viewId`, `anchorId`, `position` (works on both `record create` — insert at position — and `record update` — move existing records; only meaningful in a view without an explicit sort):

 ```bash
 inkreach-teable record update --table-id tblXXX \
@@ -269,6 +288,13 @@ inkreach-teable record update --table-id tblXXX \
  --order '{"viewId":"viwXXX","anchorId":"recYYY","position":"before"}'
 ```

+**`--field-key-type <name|id|dbFieldName>`** (default `name`): read `--fields`/`--records` keys as field ids instead of names — useful when field names contain characters that are awkward in JSON keys, or when you already have `fldXXX` ids from `field list --json`:
+
+```bash
+inkreach-teable record create --table-id tblXXX --field-key-type id \
+  --fields '{"fldXXXX":"hello"}'
+```
+
 ### Delete

 ```bash
@@ -378,7 +404,7 @@ inkreach-teable preset delete <presetId> --table-id tblXxx
 | `singleSelect` | `"Option Name"` | (string) |
 | `multipleSelect` | `["Tag A","Tag B"]` | (array of strings) |
 | `rating` | `3` | Integer 1..max |
-| `attachment` | `[{"name":"f.png","token":"xxx"}]` | Always array of objects; update **replaces all** |
+| `attachment` | `[{"name":"f.png","token":"xxx"}]` | Always array of objects; update **replaces all**. Also accepts `[{"url":"https://…","name":"f.png"}]` (server downloads the file) and, with `--typecast`, a plain URL string — see attachment URL import below |
 | `user` | `{"id":"usrXXX","title":"Alice"}` | With `--typecast`: just `"Alice"` or `"alice@example.com"` |
 | `link` | `[{"id":"recXXX"}]` | With `--typecast`: just `"Linked Record Name"` |
 | `formula` / `rollup` / `lookup` | Read-only | Cannot be set via record create/update |
@@ -404,4 +430,5 @@ inkreach-teable preset delete <presetId> --table-id tblXxx
 | View data in kanban board | `view create --type kanban` then `view update --group` | Creating special columns |
 | Set datetime in a date field | `"2025-06-15T14:30:00.000Z"` | `"2025-06-15 14:30"` (non-ISO; may be rejected) |
 | Update attachments | Always pass the full array (replaces all) | Trying to add/remove individual attachments |
+| Attach a file by URL | `record create --fields '{"Files":[{"url":"https://…/f.png"}]}'` (object form, no typecast needed) or `--typecast --fields '{"Files":"https://…/f.png"}'` | Uploading via the attachments signature/notify endpoints first (only needed for local files) |
 | Batch insert 500 records | One `record create --records` call | 500 separate `record create` calls |