Linkfox Smart Table

智能表格（LinkFox 在线多维表格）

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

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

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

功能索引

核心链路

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

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

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

往附件列放图、再取图片地址：没有附件列先 addFields 加一列 type: "attachment" → 行不存在先 createRecords → uploadAttachment（每次一张，串行）→ 要看图时 listRecords 取 presignedUrl（约 3 小时有效，现取不存）。

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

给多维表加自动化：流本身在工作流侧建（本技能不建、不改、不删流）→ 拿到 flowId 后 registerWorkflow 挂到多维表 → 要监听某张表用 updateWorkflowTriggerTable 设触发表。

通用规则

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 拿。任何 id 都不要自己编。
5. 新增 ≠ 修改：表里还没有这一行用 createRecords，已有这一行用 updateRecords。拿不准先 listRecords 看一眼 —— 用错方向不会报错，只会多一行重复数据。
6. 不可逆操作（deleteFields / deleteRecords / unregisterWorkflow）脚本要 --yes 才执行。加 --yes 之前先向用户复述要删/解除的具体对象并得到确认。
7. 写入不进撤销栈：用户在页面上按 Ctrl+Z 撤不回来。写错了只能再改回去或删掉重写。
8. 报错时把 errmsg 原文转述给用户（错误信息是按「调用方能照着改」写的），并说明这次有没有改动生效。
9. 范围：只能看到、写到调用方自己团队里自己有权限的表；跨团队拿到的 tableId 会被拒（403 / 404）。身份由网关注入的头决定，请求体里的身份字段一律被忽略。

调用与输出

• 网关地址取环境变量 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 内联中文。
• 不计费（读写的是自己团队的数据）。

通用错误码（各操作特有的错误见对应 reference 的「常见错误」）：

反馈

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