.pouch/docs/ack-feishu-bug-intake.md

ACK 飞书多维表格 Bug 收件箱

目标

让用户在飞书多维表格中跨设备记录文字和截图，由 ACK Coordinator 在同一记录补全并 反复修订修复逻辑与验收标准。用户明确审核通过后，才将批准版本整理为独立、可验收、 可幂等追踪的 ACK 任务并启动三角色闭环。

非目标

• 不用 Skill 承担人工记录入口。
• 不抓取公开网页或依赖浏览器登录态。
• 不把 App Secret、access token 或飞书用户凭据写入项目。
• 不在审核前把草案写入 tasks.yaml，也不把 ACK 执行状态持续双向同步到飞书。
• 不把多条互不相关的 Bug 合成一次 Developer 派发。

项目配置契约

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

字段	约束
provider	固定为 feishu-base
workflow	审核前协作固定为 reviewed-writeback-v1；缺省表示旧只读模式
profile	lark-cli profile 名称；每次命令显式传入
baseToken	飞书 Base token
tableId	数据表 ID
viewId	只包含可导入记录的 ACK Ready 视图 ID
fields	逻辑字段到飞书字段 ID/名称的映射

fields 必须映射 title、actual、expected、stepsToReproduce、 acceptance、priority、attachments、updatedAt。启用审核前协作时还必须映射 fixLogic。字段值只作为单个 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 和投影字段。
• 草案写回只通过读取器的 write-draft 子命令调用 base +record-upsert，并且只允许修改 配置映射的 fixLogic 与 acceptance。
• 批准后只通过 import-approved 生成规范任务字段和可重算的 approvedPayloadHash；任务 校验器拒绝审核字段与该 hash 不一致的 reviewed task。
• 记录超过一页时按 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；
• 绑定来源事实、附件元数据和审核字段的 draftRevision；
• title、actual、expected、steps、可选 fixLogic、acceptance、priority；
• enrichmentRequired：缺失但允许 Coordinator 整理的 steps、fixLogic、acceptance、priority；
• 附件的 name/type/size 与可选本地临时路径；附件 token 只在下载命令内部使用；
• 原始字段中无法映射但不影响导入的警告。

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

Coordinator 整理规则

1. 先运行读取器 check 确认 lark-cli 和项目 profile，再单独核对 app 已获得所需读写 scope；check 不把用户 token 状态当作 app/bot scope 证明。
2. 运行读取器 plan 读取 ACK Ready 视图并生成 create/refresh/unchanged/drift 整理动作；需要看截图时使用临时下载目录。
3. 将记录分类并在飞书补全 fixLogic 与 acceptance；用户反馈时继续写回同一记录。
4. 用户必须明确批准当前 draftRevision；通过前不写 tasks.yaml、不派发角色、不修改 应用代码。通过后每条导入任务保存 source.kind=feishu-base、source.ref、 source.recordId、source.updatedAt、source.workflow、source.approvedRevision、 source.approvedPayloadHash，并把截图观察转成文字证据。
5. 导入前扫描已有任务的 source.ref。相同来源不得新建第二条任务。
6. 来源更新但任务尚为 open 时可由 Coordinator刷新描述；任务已派发或进入终态时只报告漂移，由用户决定是否新开任务。
7. 飞书记录删除、不可访问或 CLI 暂时失败时保留已有 ACK 任务，不反向删除。
8. title、actual、expected、updatedAt 是不可推断的来源事实，部分缺失时 fail closed； steps、fixLogic、acceptance、priority 缺失时由 Coordinator 根据来源事实和项目上下文 补齐并写回飞书。只有批准后的最终版本才导入任务板。
9. 没有附件且所有 Bug 内容字段均为空的误建行跳过并输出 blank_record_skipped；带部分 来源事实的残缺行不得静默跳过。

可观测验收信号

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

最脆弱假设与降级

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