77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
# 飞书 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 都会被拒绝：
|
|
|
|
```bash
|
|
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、进程参数或项目文件：
|
|
|
|
```bash
|
|
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。
|
|
|
|
## 使用
|
|
|
|
```bash
|
|
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` 会直接失败。
|
|
|
|
子进程只收到实际账号 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 任务一律保留。
|