ACK 飞书多维表格 Bug 收件箱

目标

让用户在飞书多维表格中跨设备记录文字和截图，随后由 ACK Coordinator 通过官方 lark-cli 读取项目配置的 ACK Ready 视图，整理为独立、可验收、可幂等追踪的 ACK 任务。不同项目通过不同 CLI profile 访问各自飞书租户。

非目标

不用 Skill 承担人工记录入口。
不抓取公开网页或依赖浏览器登录态。
不把 App Secret、access token 或飞书用户凭据写入项目。
第一版不反向更新飞书记录，不把飞书状态与 ACK 状态做双向同步。
不把多条互不相关的 Bug 合成一次 Developer 派发。

项目配置契约

可选配置位于 docs/ack/tasks.yaml 的 project.bugIntake。未配置时 ACK 保持现有行为。配置存在时必须包含：

字段	约束
`provider`	固定为 `feishu-base`
`profile`	`lark-cli` profile 名称；每次命令显式传入
`baseToken`	飞书 Base token
`tableId`	数据表 ID
`viewId`	只包含可导入记录的 `ACK Ready` 视图 ID
`fields`	逻辑字段到飞书字段 ID/名称的映射

fields 必须映射 title、actual、expected、stepsToReproduce、 acceptance、priority、attachments、updatedAt。字段值只作为单个 argv 传给 lark-cli，不经过 shell。

CLI 契约

可执行文件固定为可信路径中的 lark-cli。
允许官方 npm 包生成且 package/bin 映射校验通过的 run.js wrapper，并解析到包内 native binary 执行；拒绝缺少 native binary 或其它同名软链接目标。
profile 由项目显式选择；不得执行 profile use 或读取 active profile作为回退。
子进程使用最小环境，不继承可能覆盖 profile/config/凭据或注入运行时的环境变量。
记录读取使用 base +record-list、JSON 输出、指定 Base/table/view 和投影字段。
记录超过一页时按 offset/limit 继续读取，并设置总页数/记录数上限。
附件仅通过 base +record-download-attachment 下载到调用者显式提供的临时目录。
附件数量、单文件大小、批次总大小和子进程文件写入均有硬上限；落盘大小必须与元数据一致。
标准输出必须是单一 JSON；CLI stderr 只作为错误摘要，不把可能的凭据写入结果。

标准化结果

读取器输出批次元数据和 records。每条记录至少包含：

sourceRef：对 provider、profile、Base、table、record ID 做域隔离 SHA-256 后得到的稳定匿名引用；原始 profile、Base token 与 record ID 不拼入引用文本；
recordId 与 updatedAt；
title、actual、expected、steps、acceptance、priority；
附件的 name/type/size 与可选本地临时路径；附件 token 只在下载命令内部使用；
原始字段中无法映射但不影响导入的警告。

输出不得包含 App ID、App Secret、Base token、附件 file token、tenant/user access token 或 CLI 配置文件内容。

Coordinator 整理规则

先运行读取器 check，确认 lark-cli、项目 profile 和所需只读能力可用。
运行读取器 plan 读取 ACK Ready 视图并生成 create/refresh/unchanged/drift 整理动作；需要看截图时使用临时下载目录。
将记录分类为 Bug、已有功能、接受的改进、样式偏好或超范围；只导入确认接受的项。
每条导入任务保存 source.kind=feishu-base、source.ref、source.recordId、 source.updatedAt，并把截图观察转成文字证据。
导入前扫描已有任务的 source.ref。相同来源不得新建第二条任务。
来源更新但任务尚为 open 时可由 Coordinator刷新描述；任务已派发或进入终态时只报告漂移，由用户决定是否新开任务。
飞书记录删除、不可访问或 CLI 暂时失败时保留已有 ACK 任务，不反向删除。

可观测验收信号

两个假租户 profile 同时存在时，项目指定 tenant-b，所有记录和附件命令都显式包含 --profile tenant-b，不会读取 active 的 tenant-a。
只读取配置的 ACK Ready view ID，并投影配置字段；不查询整张表或其它视图。
一条含截图附件的假记录被标准化为稳定 sourceRef、完整文字字段和本地附件路径，输出中不存在任何 secret/token 凭据。
CLI 缺失、profile 缺失、畸形 JSON、错位矩阵、分页越界、路径穿越或附件下载失败均返回非零退出码且不输出伪成功结果。
ACK 文档明确要求按 source.ref 幂等整理；同一读取结果重复提交不会生成第二个来源任务。
现有无 bugIntake 的 ACK 项目仍能通过任务板校验并按原流程工作。

最脆弱假设与降级

本设计假设官方 lark-cli 的 Base JSON 输出保持 fields、record_id_list 与行矩阵对应关系。读取器必须校验三者长度和字段映射；若上游输出契约变化，立即失败并提示升级适配器，不能错列生成 Bug。飞书或 CLI 不可用时，只停止新的同步，已经进入 tasks.yaml 的任务继续按 ACK 闭环执行。

5.1 KiB Raw Blame History Unescape Escape