yuxuanhui
dcd6d44960
- Added new documentation for the Feishu user authorization flow, detailing the backend protocol, authorization initiation, callback handling, and token management. - Updated frontend index to link to the new authorization flow documentation for better accessibility and guidance on UI design consistency.
97 lines
8.0 KiB
Markdown
97 lines
8.0 KiB
Markdown
---
|
||
id: 20260725-feishu-cli-base-wiki-tracker
|
||
title: 用飞书 CLI 将 Base 与 Wiki 组合为可验证的 Issue Tracker
|
||
created: 2026-07-25
|
||
updated: 2026-07-25
|
||
status: validated
|
||
scope: global
|
||
category: workflow
|
||
confidence: high
|
||
last_verified: 2026-07-25
|
||
promotion_target: none
|
||
projects:
|
||
- matt-pocock-skills-feishu
|
||
tags:
|
||
- feishu
|
||
- lark-cli
|
||
- issue-tracker
|
||
- base
|
||
- wiki
|
||
---
|
||
|
||
# 用飞书 CLI 将 Base 与 Wiki 组合为可验证的 Issue Tracker
|
||
|
||
## Trigger
|
||
|
||
当工作流要用飞书多维表格管理 Issue、任务或产物状态，同时用飞书知识库承载 PRD、Spec、Map、研究、诊断、ADR 等长文档时，召回这条经验。
|
||
|
||
## Context
|
||
|
||
两轮真实 POC 使用 `lark-cli` 连接同一 Base 表格和 Wiki 根节点。第一轮完成 setup、字段骨架、工作流文档和单条验收记录；第二轮分别运行 Spec、Ticket 依赖图和 Triage 时间状态机。关键不是“命令返回成功”，而是形成从身份验证、资源解析、增量写入到逐层回读的闭环，并保留平台限制导致的降级证据。
|
||
|
||
Base 适合保存一行一个产物及其可查询状态；Wiki/Docs 适合保存长文本。两者通过 Base 中的规范文档链接字段关联。CLI 命令和资源坐标可以进入工作流文档，但凭证、访问令牌和不必要的组织数据不能进入知识库。
|
||
|
||
## Evidence
|
||
|
||
- 2026-07-25，在 `lark-cli 1.0.76` 上完成用户身份验证、Base URL 解析、表/视图/字段回读和 Wiki 根节点解析。
|
||
- 在不删除或转换原字段的前提下，将目标表验证为共 23 个字段，包含状态、类型、负责人、进度、证据、父项和依赖等工作流字段。
|
||
- 创建并分段追加 Wiki Docx，最终回读 revision 6，确认写入内容可取回。
|
||
- 创建 Base POC 记录并用真实 record ID 回读，确认标题、文档链接、状态、完成度、验收标准和验证证据。
|
||
- 执行经验固化位置：`/Users/yuxuanhui/.agents/skills/setup-workflow-skills-feishu/references/issue-tracker-feishu.md`。
|
||
- 已省略实际 Base/Wiki URL、token、record ID 和组织信息；这些值只属于目标环境，不属于通用经验。
|
||
- 第二轮将原文本字段原地重命名为“产物文档”，保持同一 field ID、`text/plain` 类型和既有链接值；新增来源链接、外部编号、报告人、最后反馈时间、最后分诊时间后，完整字段回读为 28。
|
||
- 第二轮创建并回读 1 条 Spec、2 条 Ticket 和 1 条 Issue；Ticket 采用“两遍写入”，先建所有记录，再写父项和 blocker，逐条确认链接字段。
|
||
- Triage POC 保存 `needs-info` 阶段的时间快照，完整 `record-list` 返回 `has_more=false`，证明报告人反馈晚于上一轮分诊；随后发布 Agent Brief，并把最终再分诊时间推进到反馈之后。
|
||
- 并行执行同一 Base 的四个 `record-search` 时，三个请求返回 `800004135 OpenAPISearchRecord limited`；改为串行查询或一次完整 `record-list` 后客户端分组。
|
||
- `wiki +node-create` 返回 `131001 rpc fail`；`docs +create`（含正文与空文档两种）均返回 `10071 Document version limit reached`。搜索确认没有孤儿文档后，在已获授权的既有 Wiki 文档中追加独立 Spec/Triage 章节并回读，且明确记录该降级不等同于“新文档创建成功”。
|
||
|
||
## Root cause
|
||
|
||
已验证：飞书 CLI 集成最容易出现的可靠性缺口不是单条 API 调用，而是把“命令成功”误当成“工作流已配置”。若没有先解析真实资源、只创建缺失字段、搜索业务键防重、使用 ID 回读记录，并 fetch Wiki 文档，最终状态可能与预期不一致。
|
||
|
||
已验证：`+record-upsert` 不应被当作按业务标题自动去重。创建前必须搜索真实主字段；更新必须使用真实 record ID。
|
||
|
||
已验证：在 `lark-cli 1.0.76` 中，同表双向链接可能返回未独立出现在字段列表中的反向 ID。自动化应以正向 `所属父项` 和 `前置依赖` 为事实来源，除非当前版本回读证明反向字段可单独操作。
|
||
|
||
已验证：同一 Base 上并行发起多次 `record-search` 会触发搜索接口限流。查重和队列读取默认串行；小表可以一次完整分页读取后在客户端精确匹配，但必须检查 `has_more`。
|
||
|
||
已验证：Wiki 节点创建失败与 Docs 文档创建配额/版本限制是两个不同失败层。只有 `docs +create` 成功后才能尝试 `wiki +move`；若创建本身返回 10071，不应删除用户文档或宣称已创建，只能在授权范围内使用既有文档章节降级，或请求管理员解除限制。
|
||
|
||
## Preferred action
|
||
|
||
按以下顺序配置和验收：
|
||
|
||
1. 用 `lark-cli auth status --json --verify` 验证用户身份，不在文档中保存凭证。
|
||
2. 从用户给出的 Base table/view URL 和 Wiki root URL 解析真实 Base token、table ID、view ID、主字段、space ID、node token 和对象类型；不要按名称猜资源。
|
||
3. 在写入前完整读取 Base、table、view 和 field list，计算“仅缺失字段”的增量草稿，并让用户确认外部写入范围。
|
||
4. 串行执行 `base +field-create --json ...`。遵循每次响应中的 `field_get_recommended` 和 `next_step`，最后重新读取完整 field list。已明确授权的字段改名先用完整字段定义 `field-update --dry-run`，再以 `--yes` 写入，最后同时回读字段 ID、类型和既有单元格值。
|
||
5. 用 `wiki +node-create` 在已解析根节点下创建空白 Docx；失败时可以尝试 `docs +create` 后 `wiki +move`。若 `docs +create` 返回文档限制错误，停止创建路径，不做清理；只有既有文档更新也在授权范围内时，才使用独立章节降级。写入后用 `docs +fetch --detail with-ids` 回读内容和 revision，不对已有文档使用 `overwrite`。
|
||
6. 创建 Base 记录前，按真实主字段串行精确搜索标题。零个匹配才创建；已有记录只用真实 record ID 更新。小表改用完整 `record-list` 时必须分页到底并在客户端精确比较，不能把“第一页无匹配”当作不存在。
|
||
7. 关系图采用两遍写入：第一遍创建所有节点，第二遍使用真实 record ID 写父项和依赖，最后逐条 `record-get` 验证边。Triage 时间比较保留“反馈前的最后分诊时间”快照，最终处理后再更新最后分诊时间。
|
||
8. 创建关联 Wiki 文档的 POC 记录，包含明确验收标准和验证证据，再用 `record-get` 回读关键字段。身份字段无法可靠表达时留空并报告，不伪造用户值。
|
||
9. 只有在身份、资源、字段、Wiki 内容、POC 记录和生成的 repo 配置全部回读成功后，才宣布对应部分完成。验证被阻塞或使用降级时明确写出未满足项和原因。
|
||
10. 将实际执行过的命令写入 Wiki 工作流文档，删除凭证；保留有诊断价值的失败命令及修正版本。
|
||
|
||
建议使用的命令族：
|
||
|
||
```text
|
||
lark-cli auth status --json --verify
|
||
lark-cli base +url-resolve / +base-get / +table-get / +view-get / +field-list
|
||
lark-cli base +field-create / +field-get
|
||
lark-cli wiki +node-get / +node-create
|
||
lark-cli docs +update / +fetch
|
||
lark-cli base +record-search / +record-upsert / +record-get
|
||
```
|
||
|
||
## Boundaries
|
||
|
||
- 这条经验适用于 Base 作为结构化状态表、Wiki/Docs 作为长文档库的组合，不等同于飞书审批、项目或任务产品的通用集成方案。
|
||
- 字段 JSON、用户字段值、链接字段属性和命令参数必须以当前安装版本的 skill reference、`lark-cli --help` 和当前文档为准。
|
||
- 资源 token 和 ID 可能不是凭证，但仍应按最小披露原则处理；中央知识库只保留通用证据。
|
||
- 外部写入、删除、覆盖、权限调整和发布仍需遵守当前授权边界。
|
||
- “既有 Wiki 文档中的独立章节”能验证 Docs 写入和 Base 链接，但不能替代“成功新建独立 Wiki 文档”的验收证据。
|
||
|
||
## Promotion record
|
||
|
||
- Not promoted. Setup POC 与 Spec/Ticket/Triage POC 已提供两轮独立流程证据，学习状态提升为 validated；仍未跨第二个 Base/租户验证，因此暂不提升为全局执行规则。
|