# 飞书 Base Bug 整理与审核

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

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

## 项目配置与 Base 结构

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

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

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

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

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

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

## Profile 和安全边界

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

```bash
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 分钟。

## 读取与整理

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

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

Coordinator 对每条 Bug：

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

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

使用当前 `sourceRef` 和 `draftRevision` 写回：

```bash
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py write-draft \
  .pouch/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 后执行：

```bash
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py import-approved \
  .pouch/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 写回飞书：

```bash
python3 <ack-skill-dir>/scripts/feishu_bug_intake.py mark-imported \
  .pouch/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 任务。