linkfox-smart-table

读写智能表格(LinkFox 在线多维表格/数据表)的全部操作:查询官方模板、找表(我创建的、共享给我的)、查我的应用列表(含协作给我的,带进编辑器要用的 sessionId)、建多维表、加数据表、复制多维表(创建副本、按分享链接另存为副本)、删除多维表 / 数据表 / 多维表里的仪表盘、文件夹、页面、应用(移到回收站)、给它们重命名、看表头、加列删列、查记录(筛选/分页/取列)、新增/修改/删除

SKILL.md

GitHub

智能表格(LinkFox 在线多维表格)

一条统一入口,27 个操作。先在下面的功能索引里找到操作,再读它对应的 references/*.md;参数、出参、坑点都在那里。

python scripts/smart_table.py <op> '<JSON 参数>' [--inline] [--yes]

<op> 用接口名(camelCase);旧写法 create-records 这种也认。不带参数运行会打印全部操作。

功能索引

操作 用途 必填参数 最容易错的一点 细节
listOfficialTemplates 查询官方多维表格模板 无 公开 Agent 接口;分页用 pageSize templates.md
listMyTables 我创建的多维表和数据表 无(可选 notebookId 只看一个) 表在 notebooks[].tables[] 和 looseTables.tables[],两处都要找;顶层 notebookId 不是 tableId;传 notebookId 而它是共享来的会 404 并提示改用 listSharedTables tables.md
listSharedTables 别人共享给我的表 无(可选 notebookId 只看一个) 出参同样两层;自己建的不在这里(传自己建的 notebookId 会 404 并提示改用 listMyTables) tables.md
listApplications 我的应用列表(含协作给我的) 无(可选 name / notebookId / notebookName / source) 出参是一层扁平的(不像两个列表是两层);sessionId 为 null = 进不去编辑器;应用名和多维表名都是包含匹配;notebookId 看不见会 404,notebookName 没命中只是空列表 applications.md
createApplication 按模板在已有多维表里建应用 notebookId, templateId(可选 name,缺省「应用」) templateId 取 listOfficialTemplates 的 resourceId(slug,如 blank-template),不是 32 位十六进制 id(传错回 424 App template directory not found);不幂等:超时先 listApplications 确认再决定重试;同一用户同时只能建一个,撞上回 409;出参 sessionId 是进编辑器的键、sourceUrl 是源码包下载地址 applications.md
publishApplication 把改完代码的应用发上线 sessionId, sourceUrl sessionId 是创建接口返回的那个;sourceUrl 必须是改完代码后自己上传的包地址,不是创建接口给的下载地址;同一 sessionId 并发发布回 409(这次没发);出参 publishUrl 已落库 applications.md
unpublishApplication 把已发布的应用下线(取消发布) applicationId 传 applicationId(apl 开头),不是 sessionId;公开分享过的话凭据一并撤销、不可逆;重复调用是幂等的;出参 publishUrl 恒为 null applications.md
createTable 新建多维表 + 一张数据表 name 建的是容器;已有多维表要加表用 addTable;首列不能是 checkbox / attachment / lookup tables.md
addTable 往已有多维表里加数据表 notebookId, name 没有幂等键,超时重试前先 listMyTables 确认 tables.md
copyNotebook 复制整个多维表:创建副本 / 按分享链接另存为副本 notebookId 或 shareUrl 二选一 只能复制自己创建或协作的;分享链接必须是「可另存为副本」档;慢,超时先 listMyTables 确认,再用同一个 requestKey 重试 tables.md
deleteNotebook 删整个多维表(连同里面的数据表、仪表盘、文件夹、页面、应用),进回收站 notebookId, --yes 只有创建者能删,协作者一律 404;先 listMyTables 把会一起删掉的内容复述给用户 tables.md
deleteTable 删一张数据表(连记录、字段、视图),进回收站 tableId, --yes 多维表的最后一张删不了(400);只有表或多维表的创建者能删(403);以它为触发表的自动化会被置空 tables.md
deleteNotebookItem 删多维表里的仪表盘 / 文件夹 / 页面 / 应用,进回收站 itemType, itemId, --yes itemId 只从列表的 dashboards / folders / pages / applications 拿,itemType 取它所在的数组;删文件夹连里面的表一起删 tables.md
renameNotebook 改多维表的名字 notebookId, name 只有创建者能改(协作者 404);同一创建者名下重名 400(回收站里的也算);里面数据表的名字不跟着变 tables.md
renameTable 改一张数据表的名字 tableId, name 只有表或多维表的创建者能改(403);允许重名,一律按 tableId 改;多维表名不跟着变;改不了列名 tables.md
renameNotebookItem 改多维表里的仪表盘 / 文件夹 / 页面 / 应用的名字 itemType, itemId, name 创建者或「可编辑」能改(「可查看」404);只有文件夹在同一多维表内不能重名;itemId / itemType 规则同 deleteNotebookItem tables.md
listFields 看表头:字段名、类型、可选项 tableId 写数据前先调它;别靠读一行记录推字段(空单元格整个不出现) fields.md
addFields 追加新列(≤50);附件列可带 ai 建成 AI 出图列;type: "lookup" 建查找引用列 tableId, fields[] 重名直接 400;只能加,不能改列名/类型;ai 见 ai.md;查找引用只能引用自己创建的表 fields.md
deleteFields 按列名删整列(连数据) tableId, fieldNames, --yes 不可逆;传列名不是 fldXXX;先向用户复述要删哪几列 fields.md
listRecords 读记录:筛选、分页、取列 tableId 空单元格整个不出现;大表用 filter 定位,perPage ≤100 records-read.md
createRecords 往已有表加新行 tableId, records[].fields 拿它去「改」会多一行重复数据;不收 recordId records-write.md
updateRecords 改已有行(只改传了的字段) tableId, records[].recordId, records[].fields 200 也要比对 updated 与入参条数:查不到的 id 被静默跳过 records-write.md
deleteRecords 按 recordId 删行 tableId, recordIds, --yes 物理硬删、全有全无:一个 id 不存在就一条都不删 records-write.md
uploadAttachment 往附件列一格追加一份文件(任意类型:图片、视频、PDF、Excel 等) tableId, recordId, fieldName, 来源四选一:imageUrl / filePath / uploadId / ticketPath 只追加、一次一份;上限按类型分档:图片 20MB、视频 50MB、Excel(xls/xlsx)50MB、其余不设专门上限(全局阈值 50MB);同一格并发追加会丢失,要串行 attachment.md
fillAiField 触发一列 AI 出图(异步) tableId, fieldName 扣调用方积分;默认只填空格,mode: "all" 会整格覆盖;单次 ≤50 行 / 整列 ≤100 行 ai.md
getAiFillStatus 查 AI 出图进度与失败原因 tableId, taskId 一行最长约 10 分钟,隔 30~60 秒查一次;失败多半是提示词引用的列为空,或参考图用不了 ai.md
listWorkflows 查流挂在哪、由哪张表触发(只读) 无 tableId 为 null = 不会触发;空列表 ≠ 流不存在;关联只能看,改要到工作流侧 workflow.md

另有内置文件上传:python scripts/upload_file.py <本地文件> [<本地文件> ...], 把文件传到 LinkFox OSS 并返回公网 HTTPS URL;不依赖 linkfox-file-upload。 详情见 references/file-upload.md。

应用开发:一条命令(优先用这个)

⚠️ 在本机执行,不要在远端沙箱里执行。 本地预览要跑 pnpm dev(Node server); 沙箱里通常没有 pnpm 或装不上依赖,会直接失败。 workbuddy / codex / Claude Code 等 agent 应把命令交给用户本地终端执行。

⚠️ 本地优先,发布必须由用户确认。 create 默认只建应用 + 下载源码,不发布; 用 create_app.py dev 本地预览、改代码,用户确认后再问「要不要发布到线上」,同意才 publish。 不要每改一点就发布。

# 1. 列应用模板,让用户选一个 resourceId
python scripts/create_app.py templates
python scripts/create_app.py templates --platform amazon --stage selection --json

# 2. 建应用 + 下载源码(默认不发布)
python scripts/create_app.py create --template amazon-search --name 我的选品库
#   可选:--notebook-id nbkXXX / --notebook-name 亚马逊选品 / --dir ./xxx
#         --force-new;--publish 才会建完立即发布(不建议)

# 3. 本地启动(pnpm dev,Node server;未登录走 SSO)
python scripts/create_app.py dev --dir ./linkfox-apps/amazon-search-aplXxx
#    浏览器打开 http://localhost:3000,用 LinkFox 账号登录后看效果;改代码也在这里改

# 4. 用户明确要发布到线上后,再发布(复用同一个 sessionId)
python scripts/create_app.py publish --dir ./linkfox-apps/amazon-search-aplXxx
#    可选:--build 发布前在本机做一次构建校验

# 修改已有应用前,先看有没有本地工作目录
python scripts/create_app.py apps --name 关键词
python scripts/create_app.py status --dir ./linkfox-apps/amazon-search-aplXxx

默认工作目录是 ./linkfox-apps/<templateId>-<applicationId>(纯英文); 应用名可以是中文,但目录名不会用中文,避免 pnpm / tar / Windows 路径问题。

脚本内部已经处理:找/建多维表、同名应用防重、409 创建锁等待、sourceUrl 立即落盘、 下载源码、打包、上传、发布、列表校验。状态在 ~/.linkfox-skill/apps/<applicationId>.json 和工作目录的 .linkfox-app.json。

关键事实:

  • createApplication 返回的源码包里 .env / .env.local 已经由服务端填好 (clientId / notebookId / applicationId),不要再覆盖成模板占位符。
  • create 默认不发布;只有 --publish 或后续 publish 才上线。执行发布时,没改代码 可以直接把创建接口给的 sourceUrl 传给发布接口(内容就是成品);改过代码则重新打包 → 上传 → 发布。
  • dev 只启动 pnpm dev(Node server),不改 .env、不注入 Key;应用默认直连 https://agent-studio-api.linkfox.vip/tool-gateway,未登录会走 SSO。
  • 存量应用没有源码下载接口:有本地工作目录的用 dev 改;没有的到 LinkFox 应用编辑器里改。
  • 完整安装/登录/开发引导见 docs/app-development-guide.md。

核心链路

只有表名、没有 tableId:listMyTables → 找不到再 listSharedTables。两处都要在 notebooks[].tables[] 和 looseTables.tables[] 里找;同名多张就列给用户挑,别自己猜。

找我的应用 / 拿应用的 sessionId:直接 listApplications(不要先 listMyTables 再翻 applications[],那个只有 itemId、名字,没有 sessionId)。按应用名找传 name,按多维表找传 notebookName 或 notebookId,只要协作给我的传 source: "shared"。sessionId 为 null 表示这个应用进不去编辑器(存量应用的正常回退),别当报错、别重试,告诉用户只能从页面打开。要删 / 改名,用它的 applicationId 当 itemId、itemType: "application"。

建一个应用、改完代码再发布:优先用上面的 create_app.py——create 默认只建应用 + 下载源码(不发布),先在本机 pnpm dev 给用户预览,用户确认要上线后再 publish;不要每改一点就发布。需要自己编排时再按下面手动链路走:listOfficialTemplates 传 {"templateType":"app"} 挑一个应用模板,拿它的 resourceId 当 templateId(不是 32 位 id,传错会回 424 App template directory not found)→ listMyTables(找不到再 listSharedTables)拿到要建在哪个多维表的 notebookId → createApplication 传 notebookId + templateId(要改名字就带 name,不传用「应用」)→ 出参三样都要留着:applicationId(删 / 改名 / 查列表用)、sessionId(进应用编辑器的对话 id)、sourceUrl(这个应用的源代码包 tar.gz,下载后自己改代码)。⚠️ sourceUrl 服务端不落库,这次没拿到就再也拿不到;上游没给时是 null,应用照样是建好的。⚠️ 不幂等:每次调用都会新建一个会话加一行应用,超时 / 连不上时先用 listApplications 看有没有多出这个应用,确认没建出来再重试;报 404 就是那个多维表不在你团队或进了回收站(两种不区分),别换 id 猜。⚠️ 同一用户同时只能建一个:上一个创建还没跑完就再调,回 409「已有应用正在创建中」——这跟多维表、模板都无关,等它跑完再调即可(锁最长 2 分钟自己过期),409 时没有建出应用、不是失败重试。同一个多维表里用同一个模板建多个应用是正常需求,不拦。能建表的人才能建应用(同一个容器写权门)。

发布改完代码的应用:先在本地 pnpm dev 让用户确认,再问是否发布到线上;同意后用 create_app.py publish --dir <工作目录>。手动链路:用 createApplication 出参的 sourceUrl 下载源码包 → 改代码 → 把改完的整包传到一个公网可读地址 → publishApplication 传 {"sessionId":"<创建出参那个 sessionId>","sourceUrl":"<你自己上传的新地址>"} → 出参 publishUrl 就是发布地址,已落库,listApplications 也读它。⚠️ 两个 sourceUrl 别搞混:创建接口给的是下载地址(原始代码);完全没改代码时可以直接把它传给发布接口(服务端会下载解包再构建,内容就是成品),但一旦改过代码就必须传你自己上传的新地址。⚠️ 同一 sessionId 并发发布回 409「这个应用正在发布中」——按 sessionId 挡的,跟多维表无关,这次没有发布,等它跑完用同样的参数再发一次(锁最长 2 分钟自己过期);重复发布同一个 sessionId 是安全的,换新 sourceUrl 再发就是「用新代码覆盖上线」,这正是迭代的方式。⚠️ 失败时本地一个字节都不写:publishUrl 保持原样(可能是上一次发布的地址,也可能是空),别把失败当成「已下线」。权限与创建同一道门(能往那个多维表里写东西);「可查看」和无权一律 404。

把一个应用下线(取消发布):listApplications 按应用名找到它,拿 applicationId(apl 开头)→ unpublishApplication 传 {"applicationId":"<上一步那个>"}。⚠️ 入参是 applicationId,不是 sessionId —— 用哪个会话由服务端从应用关联行上取。⚠️ 公开分享过的应用,下线时那条公开凭据一并撤销且回不来:之后重新发布为「公开」会铸新链接,之前发出去的旧链接永久失效;下线前如果用户把链接发给了别人,先把这个后果说清楚。⚠️ 幂等:重复调是安全的(不像发布那样撞 409)。⚠️ 失败时本地一个字节都不写,publishUrl 还是上次发布的地址,别把失败当成「已下线」;成功时出参 publishUrl 恒为 null。权限同创建 / 发布(容器写权门);「可查看」和无权一律 404。

建一张表并写数据:createTable(只建结构,不收数据)→ 拿出参的 tableId → createRecords → 拿返回的 recordId 留着后续改删。已有多维表里再加一张用 addTable。

复制一个多维表(创建副本 / 另存为副本):自己能看到的多维表 → listMyTables / listSharedTables 拿 notebookId → copyNotebook;别人发来的分享链接 → 直接 copyNotebook 传 shareUrl(设了密码再带 password)。⚠️ 只有 /share/shr… 才是分享链接;用户给的是数据表页面地址(/table/<baseId>/<tableId>)时不要塞进 shareUrl,按地址里的 tableId 在 listMyTables / listSharedTables 里找到它的 notebookId 再复制。副本连同数据表、仪表盘、自动化、页面一起复制,归调用者本人。出参 tables[].tableId 全是新的,后续读写用它们,别用源表的 id。超时先 listMyTables 看副本在不在,再决定要不要重试。

删除多维表 / 数据表 / 仪表盘 / 文件夹 / 页面 / 应用:listMyTables(找不到再 listSharedTables)定位要删的对象和它的 id → 向用户复述要删的是哪个、会连带删掉什么(删多维表 = 里面全部内容;删文件夹 = 各数组里 folderId 指向它的那些)→ 用户明确同意后 deleteNotebook / deleteTable / deleteNotebookItem 加 --yes。一律进回收站,还原只能由用户在网页左侧栏底部的「回收站」里操作,本技能没有还原接口;在回收站里放满 30 天会被自动彻底删除、找不回来,跟用户说「能还原」时要带上这一句。报 400「关联列」时什么都没删:把报错里列出的列告诉用户,同意后才带 allowBreakingLinks: true 重试(那些列会变成单行文本,还原也转不回来)。这里的「页面」指多维表里的页面节点,与 linkfox-smart-table-page 技能无关。一次删一个,没有批量。

重命名多维表 / 数据表 / 仪表盘 / 文件夹 / 页面 / 应用:listMyTables(找不到再 listSharedTables)按名字找到对象和它的 id(数据表、仪表盘、页面、应用都可能重名,命中多个就列给用户挑,一律按 id 改)→ 多维表用 renameNotebook,数据表用 renameTable,其余四类用 renameNotebookItem。⚠️ 多维表名和里面数据表的名字互相独立,改一个不会动另一个;createTable 建出来时两者同名,用户说「把这个表改成 X」而多维表与表同名时,先问清改哪一个(都要改就分别调)。改名可逆,不用 --yes;改成原名直接回成功,超时用同样的参数重试是安全的。报 400 重名(多维表在同一创建者名下、文件夹在同一多维表内不能重名)时什么都没改:告诉用户、请他换个名字,不要自己加后缀重试。只能改名字:图标、列名都改不了(列名只能在页面上改)。

改某一格:listRecords 带 filter 按字段名定位,拿到 recordId → updateRecords 只传要改的那一个字段(其余字段原样保留)。命中多条就让用户挑,别按「第几行」定位。

往附件列放文件(图片、视频、PDF、Excel 等任意类型)、再取查看地址:没有附件列先 addFields 加一列 type: "attachment" → 行不存在先 createRecords → uploadAttachment(给 imageUrl 让服务端下载,或给 filePath 由脚本直传 S3;每次一份,串行;上限图片 20MB / 视频 50MB / Excel 50MB,其余走全局 50MB)→ 要看时 listRecords 取 presignedUrl(约 3 小时有效,现取不存;点开是下载,视频在页面里没有播放器)。

AI 生成图片(如商品图 → 场景图):addFields 加一列 type: "attachment" 并带 ai(提示词,可选参考图来源列,模型不写用默认)→ 配了参考列的话先把图传好 → fillAiField 触发(会扣用户积分,先说清楚)→ 隔 30~60 秒 getAiFillStatus 查到结束 → listRecords 取图。接口建的 AI 列不会自动生成,只有 fillAiField 会。细节见 ai.md。

从另一张表取值(查找引用,如订单表按 SKU 取库存):listMyTables 拿被引用表的 tableId(只能是自己创建的)→ 对两张表各 listFields 确认列名 → addFields 加一列 type: "lookup",lookup 里写取哪列、conditions(fieldName 写对方表的列,valueFromField 写本表的列)、computeMode。这一列是算出来的,写数据时跳过。细节见 fields.md § 查找引用。

自动化(工作流):建流、选触发表、换表、停用、删流全部在工作流侧做,工作流侧保存时会自动把关联同步到多维表。本技能刻意不提供登记 / 换触发表 / 解除这类写操作——只改多维表这一侧、工作流侧的订阅不跟着变,两边对不上,自动化会静默不触发。这里只能用 listWorkflows 查看关联;tableId 为 null 或该有的流不在列表里,让用户到工作流侧重新选触发表并保存。

通用规则

  1. 成功看 errcode,不看 HTTP 状态码(恒为 200)。脚本遇到业务错误会在 stderr 打 Business error: errcode=… errmsg=…,但退出码仍是 0 —— 别靠退出码判断成败。
  2. 写操作成功也要核对条数:created / updated / deleted 与入参条数不一致时,用 listRecords 查实际状态并如实告诉用户,别说「全部成功」。
  3. 字段一律按名称寻址,要与 listFields 返回的完全一致(含中英文、空格、大小写)。名字对不上会报错,不会自动建列。
  4. 三种 id 别混:notebookId(nbk,多维表容器)、tableId(tbl,数据表,在 tables[] 里)、recordId(rec,只从 listRecords / createRecords 的返回拿)。flowId 只从工作流侧或 listWorkflows 拿;仪表盘 / 文件夹 / 页面 / 应用的 itemId 只从列表接口里那个多维表的 dashboards / folders / pages / applications 拿。任何 id 都不要自己编。
  5. 新增 ≠ 修改:表里还没有这一行用 createRecords,已有这一行用 updateRecords。拿不准先 listRecords 看一眼 —— 用错方向不会报错,只会多一行重复数据。
  6. 删除类操作(deleteFields / deleteRecords / deleteNotebook / deleteTable / deleteNotebookItem)脚本要 --yes 才执行。加 --yes 之前先向用户复述要删的具体对象(以及会连带删掉的东西)并得到确认。后三个进回收站、能在页面上还原;这不是跳过确认的理由。
  7. 写入不进撤销栈:用户在页面上按 Ctrl+Z 撤不回来。写错了只能再改回去或删掉重写。
  8. 报错时把 errmsg 原文转述给用户(错误信息是按「调用方能照着改」写的),并说明这次有没有改动生效。
  9. 范围:只能看到、写到调用方自己团队里自己有权限的表;跨团队拿到的 tableId 会被拒(403 / 404)。身份由网关注入的头决定,请求体里的身份字段一律被忽略。唯一的例外是 copyNotebook 传 shareUrl:分享链接可以来自别的团队,但副本仍然只落在调用方自己团队里。

调用与输出

  • 网关地址取环境变量 LINKFOX_TOOL_GATEWAY(缺省正式地址);API Key 取 LINKFOX_AGENT_API_KEY(或 LINKFOXAGENT_API_KEY),放在 Authorization 头里,值就是 key 本身,不带 Bearer。脚本已处理好,直接调脚本即可。
  • 始终把完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-smart-table-<操作>-<timestamp>.json(<session> 取自 SESSION_ID;禁止写 /tmp)。
  • 响应 ≤ 8 KB:落盘后把完整 JSON 打印到 stdout;更大时只打摘要。--inline 强制全量打印。
  • 字段名或值含中文时,JSON 参数用单引号整体包住传给脚本;不要直接 curl 内联中文。
  • 不计费(读写的是自己团队的数据)。
  • 缺 Key / 鉴权失败(401)/ 计费不足(402)时,读 references/onboarding.md,直接跑本 skill 自带的 scripts/onboarding.py(send-code / login / list-plans / order / query)。不需要安装单独的 onboarding skill。

通用错误码(各操作特有的错误见对应 reference 的「常见错误」):

errcode 含义 怎么办
400 入参不对 按 errmsg 改
401 身份未确立:网关没注入身份头,或该成员在用户中心查不到 读 references/onboarding.md,跑本 skill 自带的 scripts/onboarding.py;不需要额外安装 onboarding skill
402 计费不足 / 余额不足 同上走 scripts/onboarding.py list-plans → order 充值
403 无权:表不在你团队、你没有这个动作的权限 换表,或请表的所有者授权
404 多维表/表/记录不存在,或不在你团队里;publishApplication 还可能是这个 sessionId 不存在(或不是创建接口给的)、或那个多维表你只有「可查看」;unpublishApplication 是这个 applicationId 不存在、不在你团队、或那个多维表你只有「可查看」——三成因故意不区分,上线状态没变 用 listMyTables / listSharedTables 重新拿 id;发布 / 取消发布用 listApplications 重新确认真实的 sessionId / applicationId,别换 id 猜
409 同一个 requestKey 的请求还在进行;copyNotebook 还表示你有一个复制没跑完;createApplication 表示你上一个创建应用还没跑完(按用户挡的,跟多维表 / 模板无关,最长 2 分钟自己过期,这次什么都没建);publishApplication 表示同一个 sessionId 上一次发布还没跑完(按会话挡的,跟多维表无关,这次没有发布、publishUrl 没改);三个删除操作(deleteNotebook / deleteTable / deleteNotebookItem)表示同一个多维表里有另一个删除还在进行(这次什么都没删) 等一会儿,先用读接口(删除用 listMyTables、建 / 发布应用用 listApplications)确认上一次是否已生效,别换 key 重发;发布撞 409 时用同样的参数再发即可(同 session 重复发布是安全的)
500 服务端异常(errmsg 已消毒) 写操作重试前先用读接口确认是否已生效 —— createTable / addTable / createRecords 重试会建重;三个删除操作重试是安全的(已进回收站的回 alreadyInTrash);三个改名操作用同样的参数重试也是安全的(改成原名直接回成功)
503 数据库暂不可用 稍后重试,写操作同样先确认状态

反馈

参见 references/feedback.md。content 里写清是哪个操作(如 createRecords)出的问题。