laily
f3cd56b78e
Use ~/.pouch, the pouch CLI, and .pouch.yaml as the SSOT container. Keep the inner skills/ packages, and store ACK project state in .pouch/ack instead of docs/ack.
149 lines
7.1 KiB
Markdown
149 lines
7.1 KiB
Markdown
# 飞书 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 任务。
|