Files

T

yuxuanhui 6e0c5c35fc Add documentation for the three-stage development workflow and CLI management strategy; create a new notes file for additional insights.

2026-08-03 16:17:16 +08:00

8.0 KiB

Raw Blame History

id, title, created, updated, status, scope, category, confidence, last_verified, promotion_target, projects, tags

title

created

updated

status

scope

用飞书 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-matt-pocock-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

按以下顺序配置和验收：

用 lark-cli auth status --json --verify 验证用户身份，不在文档中保存凭证。
从用户给出的 Base table/view URL 和 Wiki root URL 解析真实 Base token、table ID、view ID、主字段、space ID、node token 和对象类型；不要按名称猜资源。
在写入前完整读取 Base、table、view 和 field list，计算“仅缺失字段”的增量草稿，并让用户确认外部写入范围。
串行执行 base +field-create --json ...。遵循每次响应中的 field_get_recommended 和 next_step，最后重新读取完整 field list。已明确授权的字段改名先用完整字段定义 field-update --dry-run，再以 --yes 写入，最后同时回读字段 ID、类型和既有单元格值。
用 wiki +node-create 在已解析根节点下创建空白 Docx；失败时可以尝试 docs +create 后 wiki +move。若 docs +create 返回文档限制错误，停止创建路径，不做清理；只有既有文档更新也在授权范围内时，才使用独立章节降级。写入后用 docs +fetch --detail with-ids 回读内容和 revision，不对已有文档使用 overwrite。
创建 Base 记录前，按真实主字段串行精确搜索标题。零个匹配才创建；已有记录只用真实 record ID 更新。小表改用完整 record-list 时必须分页到底并在客户端精确比较，不能把“第一页无匹配”当作不存在。
关系图采用两遍写入：第一遍创建所有节点，第二遍使用真实 record ID 写父项和依赖，最后逐条 record-get 验证边。Triage 时间比较保留“反馈前的最后分诊时间”快照，最终处理后再更新最后分诊时间。
创建关联 Wiki 文档的 POC 记录，包含明确验收标准和验证证据，再用 record-get 回读关键字段。身份字段无法可靠表达时留空并报告，不伪造用户值。
只有在身份、资源、字段、Wiki 内容、POC 记录和生成的 repo 配置全部回读成功后，才宣布对应部分完成。验证被阻塞或使用降级时明确写出未满足项和原因。
将实际执行过的命令写入 Wiki 工作流文档，删除凭证；保留有诊断价值的失败命令及修正版本。

建议使用的命令族：

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/租户验证，因此暂不提升为全局执行规则。

8.0 KiB Raw Blame History Unescape Escape