飞书 Base Bug 整理与审核

飞书 Base 是 Bug 在审核通过前的唯一协作区。用户只需填写 标题，可选填写 详细描述，并把截图、录屏或日志放在 附件。Coordinator 结合来源事实、附件和项目现状整理 问题说明、期望效果、验收标准，但不在收件箱写修复逻辑。

审核通过前不创建或刷新 tasks.yaml 中的 ACK 任务，不得启动 worker、派发 Developer/Test 或修改应用代码。字段已填满、记录进入某个 view、用户暂时没有回复，都不等于审核通过。

项目配置与 Base 结构

docs/ack/tasks.yaml 的 project.bugIntake 必须声明 provider: feishu-base、 workflow: clarified-writeback-v1、显式 profile、baseToken、tableId、viewId 和字段映射：

fields:
  title: 标题
  details: 详细描述
  problemStatement: 问题说明
  expectedOutcome: 期望效果
  acceptance: 验收标准
  intakeStatus: 处理状态
  ackTaskId: ACK任务ID
  attachments: 附件
  updatedAt: 更新时间

人维护 标题、详细描述、附件；ACK 维护 问题说明、期望效果、验收标准；系统字段是 处理状态、ACK任务ID、更新时间。状态按 待整理 → 需补充/待审核 → 已确认 → 已导入 流转。优先级在批准后做任务规划时确定，不属于收件箱审核内容。原 read-only-v1 和 reviewed-writeback-v1 继续兼容旧项目。

结构变更必须先执行只读计划，再携带计划指纹应用；适配器只新增目标字段、迁移来源信息并调整当前 view 的可见字段，不删除旧列：

python3 <ack-skill-dir>/scripts/feishu_bug_intake.py schema-plan docs/ack/tasks.yaml
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py schema-apply docs/ack/tasks.yaml \
  --expected-schema-fingerprint <schemaFingerprint>

迁移时，旧 期望结果 会以 用户原始期望：… 合并进 详细描述，旧字段继续保留但从当前 view 隐藏；空状态初始化为 待整理。不要保存 App Secret、access token 或 profile 凭据。

Profile 和安全边界

在账号级可信目录安装官方 CLI：

npm install --global --prefix "$HOME/.local" @larksuite/cli@latest
printf '%s' "$FEISHU_APP_SECRET" | lark-cli profile add \
  --name project-feishu --app-id "$FEISHU_APP_ID" \
  --app-secret-stdin --brand feishu

使用官方 lark-cli，项目只保存 profile 名。不要依赖 active profile；所有读取、附件下载、写回和结构迁移都显式传配置 profile。profile 需要 Base 读写和附件下载权限。所需 scope 至少包括 base:record:read、base:record:write 和 docs:document.media:download。不要把 lark-cli auth check 当作 app/bot scope 的证明，它只检查当前用户的 stored user token。

适配器只搜索账号和系统的可信工具目录，子进程只收到实际账号 HOME、可信 PATH 和基础 locale；调用者环境中的凭据和运行时注入变量不会传入。不得绕过适配器直接操作 Base。每条记录最多 10 个附件、单批最多 100 个，单个附件最多 20 MiB、合计最多 200 MiB，整批下载最多 5 分钟。

读取与整理

python3 <ack-skill-dir>/scripts/feishu_bug_intake.py check docs/ack/tasks.yaml
tmpdir=$(mktemp -d)
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py fetch docs/ack/tasks.yaml \
  --output-dir "$tmpdir"
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py plan docs/ack/tasks.yaml \
  --output-dir "$tmpdir"

fetch 输出标准化 JSON，并为每条记录计算覆盖来源事实、附件身份、整理字段和状态的 draftRevision。标题和更新时间是必需来源事实；详细描述和附件可为空。问题说明、期望效果、验收标准缺失时返回 enrichmentRequired。plan 只给出查重和漂移预览，审核前不得据此创建任务。

Coordinator 对每条 Bug：

读取标题、详细描述、附件及相关产品/代码上下文；证据不足时明确假设，不伪装成用户原文。
写 problemStatement：说清现象、影响范围和边界，不包含修复方案。
写 expectedOutcome：说明正确情况下用户能观察到的行为，不包含实现方式。
写 acceptance：形成可独立复测的、可观察的标准，不扩张用户未表达的产品范围。
将草案保存为不超过 64 KiB 的 JSON，且只含上述三个键：

{
  "problemStatement": "非空字符串",
  "expectedOutcome": "非空字符串",
  "acceptance": ["非空验收项"]
}

使用当前 sourceRef 和 draftRevision 写回：

python3 <ack-skill-dir>/scripts/feishu_bug_intake.py write-draft \
  docs/ack/tasks.yaml --record-id <record-id> \
  --expected-source-ref <sourceRef> \
  --expected-draft-revision <draftRevision> --input <draft.json>

适配器在写前检查记录仍位于配置 view 且 revision 未漂移，只覆盖问题说明、期望效果、验收标准和处理状态（设为 待审核），随后回读并返回新 revision。把新 revision 连同整理结果交给用户审核。用户反馈后重新读取、修订和写回；不要在聊天或本地维护分叉版本。

审核门禁与导入

只有用户针对当前 revision 明确表示审核通过，并由用户本人在飞书把处理状态改为 已确认，才可继续导入。Coordinator 使用的适配器不提供把草案自行标成已确认的命令；状态和任务 ID 不参与内容 revision，因此用户确认状态不会改变已批准内容的 revision。

重新读取并核对状态和 revision 后执行：

python3 <ack-skill-dir>/scripts/feishu_bug_intake.py import-approved \
  docs/ack/tasks.yaml --record-id <record-id> \
  --expected-source-ref <approved-sourceRef> \
  --expected-draft-revision <approvedDraftRevision>

任一来源事实、附件或整理字段变化都会使旧批准失效。导出的 taskDraft 把问题说明映射为 description、期望效果映射为 expected、验收标准映射为 acceptanceCriteria；不包含修复逻辑、复现步骤或优先级。Coordinator 在后续任务规划中补充优先级，但不得改写已审核字段；校验器会重算 approvedPayloadHash。

把 taskDraft 写入 tasks.yaml、补齐任务 ID 和规划字段并通过任务板校验后，再把最终任务 ID 与同一批准 revision 写回飞书：

python3 <ack-skill-dir>/scripts/feishu_bug_intake.py mark-imported \
  docs/ack/tasks.yaml --record-id <record-id> --task-id <ack-task-id> \
  --expected-source-ref <approved-sourceRef> \
  --expected-draft-revision <approvedDraftRevision>

适配器只在任务板恰有一条 ID 匹配、来源引用、记录 ID、批准 revision 和 payload hash 全部一致的任务时，写入 ACK任务ID 并把状态推进到 已导入；回读不一致则失败。重复执行同一绑定是幂等的，不能把一条记录改挂到另一个任务。

按 source.ref 查重：仅未派发的 open 任务可刷新；其它状态只报告来源漂移，不覆盖。来源消失、不可访问或同步失败时，不删除已有 ACK 任务。

7.1 KiB Raw Permalink Blame History Unescape Escape

飞书 Base Bug 整理与审核

项目配置与 Base 结构

Profile 和安全边界

读取与整理

审核门禁与导入

7.1 KiB

Raw Permalink Blame History