HSAP/docs/FEISHU_BITABLE_OPS.md

飞书多维表格操作手册（内网）

主路径：批次登记与入湖已改为 HSAP 批次台账 + 审核入湖（BATCH_DELIVERY_OPS.md）。飞书表仅作可选人工备忘；默认 FEISHU_BITABLE_SYNC_ENABLED=0，勿再依赖 API 拉表。

配套开发说明：FEISHU_INTEGRATION_DEV.md
交接模板：FEISHU_DEV_HANDOFF.md
对象暂存（可选）：MINIO_STAGING.md
联调小样批次：PILOT_BATCH.md

内网 不要 配置多维表格「自动化 → Webhook → HSAP URL」。由 HSAP 定时 出站 回写表格（FEISHU_BITABLE_SYNC_ENABLED=1）。

---

1. 建群

项	内容
群名	HSAP·数据标注协作
成员	协调员、内部标注员、数据/运维
群公告	① 多维表格链接 ② 新批次先建表行 ③ 批次名 ≠ 任务名 ④ 内标须飞书登录 HSAP 至少一次 ⑤ HSAP：http://<内网地址>:8787（运维补充）

外协另建 HSAP·外协回传（不进主表）。

---

2. 建多维表格

1. 群内 → 多维表格 → 新建
2. Base：HSAP 数据批次台账
3. 表 1：数据批次台账（主表；采集明细表 Phase C 再做）

记下并填入 FEISHU_DEV_HANDOFF.md：

• app_token：URL /base/ 后一串
• table_id：URL 参数 table=（无则交开发用 API 查询）

---

3. 主表列（中文列名，顺序建议）

只标 addw / ddaw / addw_face 时（推荐简化）

若台账只登记单层 DMS 任务（不做 dam 0516、前向 detect 等），可以不建「子模式」列，或在各视图里 隐藏 该列。匹配与落盘只靠：

项目 + 任务 + 批次名（路径为 inbox/<任务>/<批次名>/）。

任务单选里也可只保留 ddaw addw addw_face，减少误填。

人工填写

列名	类型	必填	说明
批次编号	自动编号	是	如 001；同步到 HSAP external_id
项目	单选 dms lane	是	舱内一般用 dms
任务	单选	是	单层任务：ddaw addw addw_face；若表内也登 dam/forward 见下节
子模式	单选	可选列	仅任务为 dam、forward 时填写；单层任务不填、可删列/隐藏
批次名	文本	是	≠ 任务名；勿用训练包名 dms_v1/dms_v2，用 YYYYMMDD_场景
来源类型	单选	建议	采集车 / 回流标注 / 外协 / 实验集 / 其他
车型或场景	文本	否	溯源，如车型、工控机
采集开始 / 采集结束	日期	否
数据路径	文本	落盘前建议填	内网 NAS 绝对路径；与附件二选一
数据附件	附件	否	仅小样本 ZIP
预估张数	数字	否
备注	多行文本	否	可写训练包目标，如「合并进 dms_v2」
负责人	人员	建议	「待我处理」视图用
标注员	人员多选	标注前	内标；须已飞书登录 HSAP
外协方	文本	否	有值则走 ZIP 回传，不内标分包

何时才需要「子模式」列

任务	子模式	inbox 示例
ddaw addw addw_face	不需要	inbox/addw/20250526_SE882/
dam	填 batch_0516 等	inbox/dam/batch_0516/
forward	填 detect / classify	inbox/forward/detect/

不登 dam/forward 时：删除或隐藏「子模式」列即可，HSAP 同步不依赖该列。

状态（单选，9 项）

草稿 待落盘 分析中 待送标 标注中 待入库 已入库 落盘失败 驳回/作废

内网用法：待落盘 = 通知协调员去 HSAP 落盘；分析中 由 HSAP 回写，勿手改。

系统回写（勿手改）

候选ID、活动ID、Inbox路径、HSAP进度、HSAP链接、失败原因、最后同步、记录ID

---

4. 填写规范

1. 一批次一行；批次名 = YYYYMMDD_场景（如 20250526_SE882），不要用任务名或训练包名（addw、dms_v2）。
2. 流程：草稿 → 填齐（路径/来源/负责人）→ 待落盘 → HSAP 落盘/送标。
3. 子模式：单层任务（addw/ddaw/addw_face）一律不填；表里没有这一列也可以。
4. 训练包（dms_v1、dms_v2）写在 备注，不要写在批次名。
5. 外协：填外协方，标注员留空。

示例（addw，无子模式列）

项目	任务	批次名	来源类型	车型或场景	数据路径	状态
dms	addw	20250526_SE882	采集车	SE882电动垂卡	/NAS/.../images	草稿→待落盘

路径对照见 LABELING_SOP.md §5.2 飞书批次台账。

---

5. 视图

• 全部批次（默认）
• 待我处理：负责人=我，状态∈草稿/待落盘/待送标
• 标注中：状态=标注中

日常视图建议 隐藏：子模式（若不用）、记录ID、候选ID、活动ID（系统列可在「全部批次」保留以便核对）。

---

6. 开放平台

1. open.feishu.cn → 现有 HSAP 应用 → 权限：查看、评论、编辑和管理多维表格 → 发布
2. 表格 分享 → 添加协作者 → 企业应用 → 可管理（独立 /base/ 多维表格；wiki 内嵌见 §8）
3. 将 app_token、table_id 写入 manifests/feishu.env（见 example）

验证：bash HSAP/scripts/feishu_bitable_verify.sh（需平台已启动且 env 已填）

---

7. 自检清单

• 群 + 表 + 群公告链接
• 列与 9 态状态齐全
• 3 个视图
• 应用权限 + 表格协作者
• feishu.env 已配置 BITABLE_*
• 试填 1 行草稿（dms / addw / 批次名 20250526_test，无子模式）
• 2 名内标已飞书登录 HSAP

---

8. 文档库里加不上「企业应用」怎么办

知识库（wiki）内嵌的多维表格 + 高级权限 时，分享里往往只能加人/群，搜不到企业应用。开放平台发布版本不能代替这一步。

推荐（联调/生产）：复制为独立多维表格

1. 飞书左侧 多维表格（不要只在 wiki 里操作）→ 新建 或 从现有复制。
2. 命名如 HSAP数据批次台账-API，把列/视图按本表建好（或整库复制）。
3. 打开后地址栏为 .../base/Basc...?table=tbl... → 写入 feishu.env：
   • FEISHU_BITABLE_APP_TOKEN=Basc...
   • FEISHU_BITABLE_TABLE_ID=tbl...
   • FEISHU_BITABLE_WIKI_NODE_TOKEN=（留空）
4. 分享 → 添加协作者 → 企业应用「主动安全算法平台」→ 可管理（独立 base 一般能搜到）。
5. wiki 原表可保留给人看；HSAP 只同步 -API 这张表。群公告里可写两个链接。

临时联调（不做飞书回写）

• FEISHU_BITABLE_SYNC_ENABLED=0，台账手填；HSAP 仍用 inbox / 送标工作台。
• 小样 20260525_pilot 可照常走标注管线。

可选

• 所有者 关闭高级权限 后再试分享里加应用（不保证 wiki 仍可见应用）。
• 找飞书租户管理员确认是否允许「企业应用」担任多维表格协作者。

---

9. 已有 inbox 补录

例 inbox/ddaw/ddaw：新建一行，任务=ddaw，批次名用新命名规则，备注写「磁盘目录 ddaw」，状态按实际选待送标/标注中；HSAP 同步后会填 Inbox路径。