| name | collect-to-table |
| description | Use when 用户要把网页采集结果或已有成批结构化数据落入多维表，且数据含嵌套明细、可复用对象、关联或反查需求，或落库前需要判断单表还是多表；也用于要求可重跑、批次覆盖或采集后直接建表。 |
| metadata | {"version":"0.1.9","tabtin":{"category":"data","displayName":"采集落多维表","autoActivateFor":["tabdata","tabweb"],"tools":["run_terminal_command"],"tags":["orchestration","requires-body","collect","table"]},"runtime":"cloud","requires":{"bins":["tabtin"]},"canonicalName":"collect-to-table"} |
采集落多维表 V2
核心原则
先判断数据结构，再确认分表方案，再确认是否复用历史表，最后写入并验证。简单扁平数据可豁免分表确认；任务内新建的表可直接复用；工作区里本轮之前已有的表，写入前必须一次性问清能否复用。
输入范围
接受两类输入：
- 尚无数据：按需加载
app:tabweb/browser-collect，获得结构化采集结果。
- 已有数据：接手用户提供的 JSON、JSONL、CSV、对象数组或等价结构，不要求重新采集。
当来源是当前已登录网页时，先在 Browser Operator 中锁定当前 Tab，保留登录态与用户已经展开 / 筛选后的页面状态，再调用 app:tabweb/browser-collect 或当前 Tab 的 JSON Schema 投影形成结构化数据。不要因为来源 URL 属于某个第三方站点而切换成该站点的资产迁移 CLI。
网页采集的 bundle 必须保留来源链接与获取时间；资源或字段抓取失败时记录缺失项，不能用常识补值，也不能只凭写表命令成功就声称完整导入。
把输入统一为 CollectBundle。字段契约见 references/bundle-contract.md，仅在需要整理或检查输入时读取。
状态与阶段
依次执行，不能跳过阶段：
| 阶段 | 必须产出的状态 |
|---|
| 1. 接手数据 | bundle、task_id、预期记录数 |
| 2. 识别结构 | 主实体、明细、可复用对象及其候选键 |
| 3. 方案门闩 | confirmed_plan，或明确记录 flat_exemption=true |
| 3.5 复用门闩 | reuse_plan，并维护 task_created_table_ids |
| 4. 写入 | 表 ID、字段 ID、关联字段、实际写入数（遵守 reuse_plan） |
| 5. 验证 | 与方案对应的验收结果全部通过 |
| 6. 复盘 | 表名、条数、关联、合并策略和缺失项 |
阶段 3.5 细则见 references/reuse-plan.md。无历史候选时可写空 reuse_plan 并跳过 ask_user；有历史候选且尚无完整 reuse_plan 时，禁止进入写入。
任何阶段缺少对应状态，不得进入下一阶段。
识别数据角色
只使用通用角色，不预设业务表名：
- 主实体：用户要保存的顶层对象，一条记录对应一个主对象。
- 明细：主实体下的列表项，例如评论、SKU、章节或参与记录。
- 可复用对象：会跨多个主实体重复出现，并可能需要反查的对象，例如人员、标签或机构。
主实体和可复用对象默认按稳定业务键合并。明细默认按本次 task_id 做批次快照，不因自造明细键而自动改成长期合并。
方案门闩
先计算：
requires_confirmation =
存在嵌套列表
OR 存在两个及以上可独立存在的实体
OR 用户要求关联、一对多或跨实体反查
OR 同一可复用对象跨主实体重复出现
requires_confirmation = true
如果还没有 confirmed_plan：
- 下一次工具调用必须是
ask_user。
- 一次性展示推荐方案和替代方案。
- 收到用户选择后写入
confirmed_plan。
- 用户回复前，禁止调用任何
table create、field add、link create、import、bulk-insert、upsert、update 或其他写表命令。
确认卡使用产品语言，不说 A/B/C：
- 推荐：主实体、明细分别成表并关联；检测到可复用对象时说明是否建议单独成表。
- 备选：只建一张扁平表。
- 调整：允许用户修改分表数量、表名及追加或覆盖策略。
requires_confirmation = false
仅在以下任一可观察条件成立时设置 flat_exemption=true 并直接写一张表：
- 数据只有标量字段，没有嵌套列表、独立子实体和反查需求。
- 用户已经明确要求“一张表、扁平、不要关联”。
- 用户要求按本次对话中已经确认的方案重跑，且
confirmed_plan 仍在状态中。
不确定是否满足豁免时，按 requires_confirmation=true 处理。
复用门闩
在方案门闩完成之后、写入之前执行。完整规则读 references/reuse-plan.md。
摘要：
- 维护
task_created_table_ids（本轮 table create 成功则追加）。
- 用
table list / table info 找同角色候选；任务内表可直接复用。
- 存在历史候选且尚无完整
reuse_plan 时：下一次工具调用必须是 ask_user；用产品语言说明发现了哪些可复用历史表并询问能否复用（措辞由你按场景生成，不要求固定开场句）；默认勾选复用；提供「全部新建」与「其他」。
- 多张历史表合并一次确认，禁止逐张询问。
- 用户回复前，禁止任何写表命令（与方案门闩相同禁止清单）。
按阶段加载工兵 Skill
不要一开始批量读取所有相关 Skill：
- 没有结构化数据时，只加载
app:tabweb/browser-collect。
- 用户确认多表方案后，按需加载
app:tabdata/table-modeling 和 app:tabdata/table-association。
- 准备批量导入或需要确认值格式时，再加载
app:tabdata/table-import-export。
- 已有简单单表且只做 CRUD 时，转交
app:tabdata/table-operator，不要继续本编排。
写入与验证
进入写入阶段前，必须已有完整 reuse_plan（见 references/reuse-plan.md），再读取 references/write-and-verify.md 并按其中顺序执行。
必须满足：
- 多行写入使用批量命令；少量定向补救才允许单行操作。
- 明细同
task_id 重跑时先清除本批旧行，再写入本批全集。
- 关联值使用记录 ID 数组，不写姓名等普通字符串。
- 验收失败只定向补救；未经用户明确要求，不整表重建或整链重采。
- 所有适用断言通过前，不得向用户声称完成。
最终复盘
只在验证通过后汇报：
- 建立或复用了哪些表，以及关联方向。
- 主实体、明细、可复用对象分别写入多少条。
- 使用什么业务键合并，哪些数据按本批覆盖。
- 是否存在部分采集、失败项或弱键重名风险。
- 用户应在多维表 App 中打开哪些表查看结果。
常见错误
| 错误 | 正确处理 |
|---|
把 skills_read 当成已经执行 Skill | 任务执行必须先 skill_invoke |
| 读完 Skill 后直接说“我开始建表” | 命中方案门闩或复用门闩时，下一次调用只能是 ask_user |
| 查到历史同角色表就直接 upsert | 先走复用门闩，一次确认能否复用 |
历史表一张一张 ask_user | 合并为一张确认卡（含全部新建 / 其他） |
| 为了省事把嵌套明细塞进一个文本列 | 先让用户选择分表或扁平方案 |
| 对明细只做 upsert | 同任务重跑默认先清本批旧行再批量写入 |
| 一开始加载全部表格和浏览器 Skill | 按当前阶段只加载必要工兵 |
| 只看命令成功就宣告完成 | 读取验证参考并核对行数、关联和批次快照 |
