laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6855ac7078fe6dd5f075273f933ae76f53570d71
.pouch/skills/ack/references/feishu-bug-intake.md
T
laily 6855ac7078 feat: update feishu intake
2026-08-02 14:08:11 +08:00

5.7 KiB
Raw Blame History

飞书 Base Bug 收件箱

这是可选的只读接入。项目在 docs/ack/tasks.yaml 的 project.bugIntake 声明 provider: feishu-base、显式 profile、baseToken、tableId、ACK Ready 的 viewId 和八个字段映射；不要保存 App Secret、access token 或任何 profile 凭据。

一次性安装与 profile 设置

在账号级可信工具目录安装官方 CLI；ACK 读取器只会搜索账号的 ~/.local/bin、mise/cargo shim 目录和固定系统目录，绝不会采用项目 PATH 中的同名文件。它同时识别官方 npm 包生成的 lark-cli -> @larksuite/cli/scripts/run.js wrapper，并校验 package 名与 bin 映射，然后直接执行该官方包下载的 native binary；这样不依赖 nvm PATH，也不会让 Node 运行时变量进入凭据边界。缺少 native binary 或同名仿冒 wrapper 都会被拒绝：

npm install --global --prefix "$HOME/.local" @larksuite/cli@latest

固定 --prefix "$HOME/.local" 是接入契约的一部分，确保 npm wrapper 落在读取器会检查的 账号级可信目录；不要依赖 nvm 或其它由当前 shell 动态注入的 PATH 位置。

随后在受控终端中用 stdin 提供 App Secret，选择 Feishu brand，避免 secret 进入 shell history、进程参数或项目文件：

printf '%s' "$FEISHU_APP_SECRET" | lark-cli profile add \
  --name project-feishu --app-id "$FEISHU_APP_ID" \
  --app-secret-stdin --brand feishu

随后在 project 配置里只填写 profile: project-feishu。不要执行 profile use，也不要 依赖 active profile；每次读取和附件下载都由 adapter 显式传 --profile project-feishu。 为读取记录和下载附件，profile 必须具有 base:record:read 和 docs:document.media:download。请在飞书开发者后台的应用权限中为该 app 授予这两个 scope；不要把 lark-cli auth check 当作 app/bot scope 的证明，因为它检查的是当前用户的 stored user token。

使用

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 只调用官方 base +record-list（限定配置的 view 和字段）和按配置附件字段的 base +record-download-attachment。它输出单一 JSON，验证行矩阵、分页和下载路径；CLI、 profile、JSON、分页、附件或路径任一异常都会失败且不输出伪成功结果。

plan 在同一批标准化记录上读取现有 tasks，只输出整理计划而不修改文件：新来源为 create，同来源且现有任务为 open、来源时间有变化时为 refresh，未变化为 unchanged，其它 ACK 状态发生来源变化时为 drift。任务板或读取结果出现重复 sourceRef 会直接失败。标题、实际表现、预期结果和更新时间属于来源事实，任一缺失时 读取失败；复现步骤、验收标准和优先级属于 Coordinator 可整理字段，缺失时记录与 action 会返回 enrichmentRequired，不阻断整批。没有附件且所有 Bug 内容字段都为空的误建行会 跳过，并在批次 warnings 中返回 blank_record_skipped。

子进程只收到实际账号 HOME、可信 PATH 和基础 locale；调用者环境中的 LARKSUITE_CLI_*、FEISHU_*、NODE_OPTIONS 等变量不会传入，避免环境凭据或运行时 注入绕过项目 profile。每条记录最多 10 个附件、单批最多 100 个，单个附件最多 20 MiB、合计最多 200 MiB，整批附件下载最多 5 分钟，并校验声明大小与落盘大小； 请始终使用新的临时目录作为 --output-dir。

profile list 只作存在性检查，不会输出 profile 内容。官方 record-list JSON 使用 data.fields、data.record_id_list 与同长度的 data.data 行矩阵；ok: true 或 code: 0 是唯一可接受的成功 envelope。

Coordinator 整理

读取结果的每条 sourceRef 是稳定且不透明的键，例如 feishu-base:sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef。 导入时写入 task 的 source.kind: feishu-base、source.ref、source.recordId 与 source.updatedAt；先按 source.ref 查重。相同来源只更新 open 任务；dispatched、fixed_by_dev、 retesting、failed_retest、verified、blocked 和 leftover 任务只告警来源漂移， 由用户决定是否新建任务；飞书记录消失、不可访问或同步失败时，已有 ACK 任务一律保留。

当 action 带 enrichmentRequired 时，由 Coordinator 补齐后再写入任务板，不要求报告者 返回飞书机械补字段：

  • steps：根据标题、实际表现、附件和项目现状整理 2 至 5 个可复现步骤；证据不足时明确 写成待 Developer 首轮确认的复现假设，不能把假设伪装成来源原文。
  • acceptance：把预期结果改写成可观测信号，至少覆盖用户可见结果、真实状态或 API 结果， 以及原失败不再出现；不扩张飞书记录没有表达的产品范围。
  • priority：主流程阻断、数据损坏/丢失或安全风险定为 P0；普通功能错误默认 P1；纯样式或 低频体验问题可定为 P2。无法判断时使用 P1，并保留判断依据。

在任务 evidence.intakeEnrichment 中记录哪些字段由 Coordinator 推断及依据。Developer 必须先复现或用失败测试确认推断步骤；Test 仍按任务中的可观测验收信号独立复测。标题、 实际表现和预期结果不得由 Coordinator 补造，部分缺失时继续 fail closed。

Reference in New Issue View Git Blame Copy Permalink