维格云（Vika）记录 API 技能

用维格云 Fusion API 对维格表做记录级 CRUD：获取（GET）/创建（POST）/更新（PATCH）/删除（DELETE），并正确处理分页、筛选、字段值格式、批量上限与错误重试。

何时使用

• 从维格表读取记录做同步、报表、导出或校验（尤其是超过 1000 条的全量读取）。
• 向维格表写入/更新/删除记录（含批量导入、按条件更新、数据清理）。
• 需要按视图、公式筛选、排序、指定字段取数，或需要区分「HTTP 200 但业务失败」。
• 不适用：维格云私有化部署（API 可能存在版本差异）；非 Fusion API 的插件/小程序/脚本 API；需要 OAuth2 的场景（官方尚未开放）。

前置条件

1. API Token：维格云「用户中心 → 开发者配置」生成，权限等同 Token 所属用户本人。
2. datasheetId：维格表 URL 中 dst 开头的字符串（表 ID）；视图 ID 为 viw 开头；记录 ID 为 rec 开头；字段 ID 为 fld 开头。
3. 网络与协议：只支持 HTTPS；Base URL 为 https://vika.cn/fusion/v1（不是旧镜像域名 api.vika.cn）。
4. 环境变量：Token 放进 VIKA_TOKEN，不要硬编码到代码或命令历史中。

# Linux / macOS
export VIKA_TOKEN='你的 API Token'
# Windows PowerShell
$env:VIKA_TOKEN = '你的 API Token'

> 安全：Token 等价于用户账号权限。任何输出、日志、报错、截图、提交的脚本中都不要出现真实 Token。

标准工作流

1. 定位表：拿到 datasheetId（必要时先 GET /spaces、GET /spaces/{spaceId}/nodes 找目标表）；需要视图筛选时再取 viewId（GET /datasheets/{dst}/views）。
2. 先读字段：GET /datasheets/{dst}/fields，确认字段名/type/property（选项、是否可编辑）。不要凭猜测拼字段名。
3. 小样本读：先取 1–5 条记录，验证字段 key、日期/成员/附件值格式与筛选公式。
4. 写操作：创建/更新/删除都单次最多 10 条，超过必须分批；写前可先 --dry-run 预览；先写 1 条验证格式再批量。
5. 删除特殊处理：删除不可逆（官方未说明 API 删除可恢复），必须先列出待删 recordId 清单并获人工确认，脚本需显式 --yes。
6. 记账：估算 API 请求数（读 ceil(条数/1000)，写 ceil(条数/10)），避免月度额度（1 万/10 万/50 万/250 万次）耗尽；批量失败保留已成功明细，避免重复创建。

接口速查

完整参数、请求体、响应字段、扩展接口见 references/api-reference.md。

获取记录

GET https://vika.cn/fusion/v1/datasheets/{datasheetId}/records

# 取一页：视图 + 字段过滤 + 公式筛选 + 排序（--data-urlencode 自动 URL 编码）
curl -G "https://vika.cn/fusion/v1/datasheets/dstXXXXXXXXXXXX/records" \
  -H "Authorization: Bearer $VIKA_TOKEN" \
  --data-urlencode "viewId=viwXXXXXXXXXXXX" \
  --data-urlencode "fields[]=名称" \
  --data-urlencode "filterByFormula={状态}='进行中'" \
  --data-urlencode "sort[0][field]=创建时间" \
  --data-urlencode "sort[0][order]=desc" \
  --data-urlencode "pageSize=1000"

创建记录

POST https://vika.cn/fusion/v1/datasheets/{datasheetId}/records，Body：{"records":[{"fields":{...}}]}，单次 ≤10 条。

curl -X POST "https://vika.cn/fusion/v1/datasheets/dstXXXXXXXXXXXX/records" \
  -H "Authorization: Bearer $VIKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[
        {"fields":{"名称":"示例","数量":3,"状态":"进行中"}},
        {"fields":{"名称":"示例2","数量":5}}
      ]}'

成员字段写入用 unitId（id 属性可能停用）；附件需先上传拿 token；字段值格式见 references/field-types.md。

更新记录

PATCH https://vika.cn/fusion/v1/datasheets/{datasheetId}/records，Body：{"records":[{"recordId":"rec...","fields":{...}}]}，单次 ≤10 条；PATCH 为局部更新，只改显式字段，null 表示清空（局部更新/清空说明来自旧版接口文档，首次使用建议实测）。

curl -X PATCH "https://vika.cn/fusion/v1/datasheets/dstXXXXXXXXXXXX/records" \
  -H "Authorization: Bearer $VIKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"recordId":"recXXXXXXXXXXXX","fields":{"状态":"已完成"}}]}'

删除记录

DELETE https://vika.cn/fusion/v1/datasheets/{datasheetId}/records?recordIds=rec1,rec2，recordIds 逗号分隔放 query（不是 body），单次 ≤10 条；不可逆，先确认。

curl -X DELETE "https://vika.cn/fusion/v1/datasheets/dstXXXXXXXXXXXX/records?recordIds=recAAA,recBBB" \
  -H "Authorization: Bearer $VIKA_TOKEN"

响应包络（所有接口统一）

{"success": true, "code": 200, "message": "SUCCESS", "data": {}}

成功判据：success == true 且业务 code == 200（HTTP 201 也是 POST 成功），不能只看 HTTP 状态码。
获取记录的 data 含 total/pageNum/pageSize（本页实际条数）/records[]；删除成功 data: true。

硬性限制速查

更多限制与完整状态码见 references/limits-and-errors.md。

分页与批量策略

• 读取全量：pageSize=1000 翻页，pageNum 从 1 递增；终止条件 = 本页 0 条、或累计 ≥ data.total、或已达 --max-records。不要用固定次数盲翻。
• 按 ID 精确取：recordIds 不分页，单次 ≤1000；超过 1000 个 ID 就分段请求后按段拼接。
• 写入分批：每批 ≤10 条；批间按 QPS 限速（建议默认 5 QPS，按套餐调整）。
• 部分失败：记录每批成功/失败明细，只重试失败批、保留成功结果；创建接口不幂等，重试前先按唯一字段查询去重，避免重复记录。

get:    pageNum = 1
        loop: 取一页(pageSize=1000)
              累计记录 += 本页
              if 本页为空 or 累计 >= total or 累计 >= maxRecords: break
              pageNum += 1
write:  for batch in chunks(records, 10):
              request(batch)   # 批间 QPS 限速；429/5xx 指数退避

错误处理与重试

安全注意

• Token 只从环境变量 VIKA_TOKEN 读取；不硬编码、不写在命令行参数（会进 shell 历史）、不打印、不写日志、不提交仓库。
• 示例/文档中的 Token 一律用 $VIKA_TOKEN 或 {你的 API Token} 占位；发现真实 Token 泄露应立即在「开发者配置」重置。
• 删除是高危不可逆操作：先展示待删记录清单，人工确认后再执行；脚本须加 --yes。更新也建议先读后写、小样本验证。
• 写操作前用 --dry-run 预览；不要对生产表做无确认的大批量删除/覆盖。

附带的命令行脚本

scripts/vika_api.py 覆盖本技能全部 CRUD，自动分页、自动按 ≤10 分批、QPS 限速、429/5xx 退避、--dry-run、退出码 0/1/2。

export VIKA_TOKEN='你的 API Token'
python3 vika-api/scripts/vika_api.py get    --datasheet dstXXXXXXXXXXXX --max-records 20
python3 vika-api/scripts/vika_api.py get    --datasheet dstXXXXXXXXXXXX --filter "{状态}='进行中'" --fields 名称 状态
python3 vika-api/scripts/vika_api.py create --datasheet dstXXXXXXXXXXXX --file records.json --dry-run
python3 vika-api/scripts/vika_api.py create --datasheet dstXXXXXXXXXXXX --file records.json
python3 vika-api/scripts/vika_api.py update --datasheet dstXXXXXXXXXXXX --file updates.json
python3 vika-api/scripts/vika_api.py delete --datasheet dstXXXXXXXXXXXX --record-ids recAAA recBBB --yes

• --file/--json 输入格式：记录数组，或 {"records":[...]}；每条记录用 fields 包裹字段值（update 需带 recordId）。
• 全局选项必须写在子命令之后（如 ... create --datasheet dstX --file r.json --dry-run）：--dry-run、--qps、--base-url、--timeout、--max-retries、--retry-base、--quiet。
• --qps 默认 5（可选 2/5/10/20）；--dry-run 只打印请求不发送；删除不加 --yes 会拒绝执行并返回退出码 2。
• get --record-ids 模式不分页、按传入顺序返回，--view-id/--filter/--sort/--fields 会被忽略（脚本会提示）；脚本按 200 个/段请求以控制 URL 长度。
• 输出为 JSON 摘要（returnedRecords/createdRecordIds/failures 等），便于 Agent 解析；失败时退出码非 0。
• 详细用法：python3 vika-api/scripts/vika_api.py get --help（含全局选项），根命令 --help 查看子命令列表。

深入阅读

• 接口全参、请求体、响应字段、扩展接口（字段/视图/空间站/附件）：references/api-reference.md
• 各字段类型写入格式（成员/附件/日期/关联等）与只读字段：references/field-types.md
• 频率/接口/用量限制、状态码、重试退避、排查清单：references/limits-and-errors.md
• 调研来源、设计决策与评审记录：NOTES.md（维护者阅读，执行任务时不必读）

快速故障排查

1. 401 身份认证失败：VIKA_TOKEN 是否设置进当前进程、是否过期、请求头是否为 Authorization: Bearer {token}（Bearer 后有空格）。
2. 200 但返回失败：看 success/code/message——301 表不存在或不可见、602 无权限、304 行数上限、400 字段名/值格式错误。
3. 429 操作太频繁：降低 --qps，等待退避后重试；不要并发猛打同一张表。
4. 取数不全：是否只取了第一页；pageSize 是否 ≤1000；total 是否大于已取数量。
5. 写入报 400：先 get-fields 核对字段名/类型；成员是否用 unitId；单选/多选选项是否存在；日期格式是否匹配。
6. 删除/更新异常：确认 recordId 属于该表（记录 ID 只在表内唯一）；确认没有拿错 datasheetId。