sakibcc/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dd318e2422f74ad40af95448d3f62dd1c4729f30
obsidian-vault/output/研究文章/Matt 工作流 × 飞书 CLI 全流程总结.md
T
yuxuanhui dd318e2422 feat:更新
2026-08-31 09:21:12 +08:00

29 KiB
Raw Blame History

Matt 工作流 × 飞书 CLI 全流程总结

状态：已通过真实 Feishu Base / Wiki POC 验证
更新时间：2026-07-26
覆盖范围：setup-workflow-skills-feishu、to-spec-feishu、to-tickets-feishu、triage-feishu

1. 结论

本次工作把 Matt Pocock 的工程工作流接入了飞书，并保持原 Matt skills 的规划、规格、垂直切片和分诊语义不变：

  • Feishu Base 是状态、关系和查询的事实来源：每个 Issue、Spec、Ticket 或其他产物对应一条记录。
  • Feishu Wiki / Docs 是长文档事实来源：保存 Spec、Triage Notes、Agent Brief、Human Brief 等叙述性产物。
  • 仓库仍保存代码侧事实：代码、测试、ADR、CONTEXT.md 和被拒绝 enhancement 的 .out-of-scope/ 决定不会复制成第二份事实来源。
  • 所有 Feishu API 操作使用应用身份：--as bot --format json，不回退到 user 身份或其他文档位置。
  • 每次 Base 记录创建或更新都记录真实发起用户：调用者是 bot，“最后更新人”保存当前 CLI 人类用户；“负责人”仍只表示执行责任人。
  • 所有写入都需要回读验证：API 返回 ok:true 只是第一层证据，Wiki 用 docs +fetch，Base 用 record-get 或完整分页查询复核。

2. 当前资源与身份

项目 当前值
Base Matt 工作流多维表格
Base token HXzGbaFIAaHEpBsMMrfc0z1lnnb
数据表 数据表 / tblFvlnVuWhmvQKC
主字段 文本 / fldzLHLTca
视图 表格 / vewwNwcwaf，29 个字段全部可见
Wiki 根节点 开发智能体文档仓库
Wiki space 7493342321238130707
工作流文档 Matt 工作流 × 飞书 CLI：文档与进度管理工作流
API 执行身份 bot 迷迭香 / ou_967b892ae067fd2e24d369a289a5b01e
当前归因用户 于选辉 / ou_aed469c8168cd31341fa94bf2d89bddd
已验证 CLI lark-cli 1.0.76

3. 系统架构

flowchart LR
    Human["真实用户 / 维护者"] --> Conversation["对话确认与 Matt 工作流"]
    Conversation --> Auth["auth status --verify"]
    Auth -->|"验证 bot"| Bot["应用身份：迷迭香"]
    Auth -->|"冻结 user openId"| Attribution["业务归因：最后更新人"]

    Bot -->|"--as bot"| Base["Feishu Base\n状态、关系、查询"]
    Bot -->|"--as bot"| Wiki["Feishu Wiki / Docs\n长文档与叙述"]
    Attribution -->|"每次 record create / update"| Base

    Repo["代码仓库\n代码、测试、CONTEXT、ADR、out-of-scope"] --> Conversation
    Base -->|"产物文档"| Wiki
    Base -->|"代码引用"| Repo

    Base --> Verify["record-get / 完整分页回读"]
    Wiki --> VerifyDoc["docs +fetch 回读"]
    Verify --> Evidence["验证证据"]
    VerifyDoc --> Evidence

关键边界：

  1. bot 是 API 调用者，不自动等于“负责人”或“最后更新人”。
  2. “最后更新人”由工作流显式写入当前已验证用户的 open ID。
  3. “负责人”是工作执行责任，不因 CLI 操作而被覆盖。
  4. Wiki 节点必须创建在配置的根节点下；失败时报告完整错误和 x-tt-logid，不切换身份或位置重试。

4. 四个 Feishu skill

Skill 何时使用 核心输入 核心产物 Base / Wiki 策略
setup-workflow-skills-feishu 仓库接入或切换到飞书 tracker Base 表格/视图 URL、Wiki 根节点 URL、Setup 模式 repo tracker 合约；Bootstrap 另含 Base schema、Wiki setup 文档、POC 记录 默认 Reuse 只读复核既有设施；Bootstrap 才初始化并验证写路径
to-spec-feishu 把已澄清的对话转成可执行 Spec 对话、代码库上下文、测试 seam、可选来源 Issue 完整 Wiki Spec + 一条 Base Spec Wiki 保存完整规格；Base 保存身份、状态、摘要、验收和父项
to-tickets-feishu 把 Spec / 计划拆成 tracer-bullet Tickets 已确认 Spec、垂直切片、依赖图 每个切片一条 Base Ticket V1 不创建 Ticket Wiki；通过父 Spec 取得文档；两遍写入关系
triage-feishu 处理 Issue / PR 的分类、澄清和委派 Issue/PR、代码验证、维护者决定、报告人反馈 Base Issue 状态 + 可选 Triage Wiki dossier Base 保存当前状态；Wiki 追加 Notes / Brief；拒绝决定以 repo 为准

这些 skill 的 来源技能仍使用逻辑流程名，例如 setup-matt-pocock-skills、to-spec、to-tickets、triage；不会把适配器名称写成新的业务枚举。

5. 端到端工作流

flowchart TD
    Setup["setup-workflow-skills-feishu\n建立 repo 合约；按模式复用或初始化飞书资源"] --> Intake{"工作从哪里进入？"}

    Intake -->|"想法 / 已澄清对话"| SpecDraft["to-spec-feishu"]
    Intake -->|"外部 Issue / PR / 表单"| Triage["triage-feishu"]

    Triage --> NeedsInfo["needs-info\n等待报告人"]
    NeedsInfo -->|"最后反馈时间 > 最后分诊时间"| Triage
    Triage --> ReadyAgent["ready-for-agent"]
    Triage --> ReadyHuman["ready-for-human"]
    Triage --> Wontfix["wontfix / out-of-scope"]

    ReadyAgent --> Complexity{"是否需要正式 Spec？"}
    Complexity -->|"跨模块、需要设计决策"| SpecDraft
    Complexity -->|"范围已足够小且明确"| Implement["implement / tdd"]

    SpecDraft --> SpecArtifacts["Wiki Spec + Base Spec\n状态 ready-for-agent"]
    SpecArtifacts --> Ticketing["to-tickets-feishu"]
    Ticketing --> TicketGraph["Base Ticket 依赖图\nfrontier = 无未完成 blocker"]
    TicketGraph --> Implement

    Implement --> Review["code-review / 验证"]
    Review --> Done["已完成 + 验证证据"]
    Implement --> Blocked["阻塞 + 阻塞原因 + 下一步"]
    Blocked --> Implement

    ReadyHuman --> HumanWork["人类处理：判断、权限、设计或手工验证"]
    Wontfix --> Memory["Wiki 关闭说明；必要时 repo .out-of-scope/"]

本次新增的硬依赖飞书适配止于 setup、Spec、Tickets 和 Triage；implement、tdd、code-review 等下游流程通过生成的 docs/agents/issue-tracker.md 公共合约继续消费同一 Base。

6. Setup：一次性建立公共契约

flowchart TD
    Start["探索仓库"] --> Detect["检查 AGENTS/CLAUDE、docs/agents、domain docs、triage、monorepo"]
    Detect --> Tracker{"选择 issue tracker"}
    Tracker -->|"Feishu"| Inputs["只接受两个用户输入\nBase URL + Wiki 根 URL"]
    Inputs --> ReadSkills["读取 lark-shared / base / wiki / doc 规则"]
    ReadSkills --> Mode{"选择 Setup 模式\n默认 Reuse"}
    Mode -->|"Reuse：复用已配置资源"| Identity["验证 bot + user；冻结当前 user openId"]
    Mode -->|"Bootstrap：新建或显式重验"| Identity
    Identity --> Resolve["bot 解析 Base、table、view、Wiki root"]
    Resolve --> Diff["完整 field-list；按精确字段名计算缺失项"]
    Diff --> ReuseCheck{"选择的是 Reuse？"}
    ReuseCheck -->|"是，schema 完整"| ReuseDraft["展示 repo 文件与只读验证证据\n明确不会写 Base / Wiki"]
    ReuseCheck -->|"是，但发现 drift"| ReuseStop["停止；询问切换 Bootstrap\n或单独授权 schema repair"]
    ReuseCheck -->|"否"| BootstrapDraft["展示 repo 文件、缺失字段、Wiki 标题、POC 标题"]
    ReuseDraft --> ReuseConfirm{"用户确认 repo 文件？"}
    ReuseConfirm -->|"否"| ReuseDraft
    ReuseConfirm -->|"是"| RepoContract["生成 docs/agents/issue-tracker.md\n以及 triage/domain 合约"]
    BootstrapDraft --> BootstrapConfirm{"用户确认 Bootstrap 写入？"}
    BootstrapConfirm -->|"否"| BootstrapDraft
    BootstrapConfirm -->|"是"| Schema["只创建缺失字段；不静默转换冲突字段"]
    Schema --> WikiSetup["根节点下创建 Wiki setup 文档；append + fetch"]
    WikiSetup --> POC["创建 POC Base 记录；record-get"]
    POC --> RepoContract
    RepoContract --> Gate{"验证门通过？"}
    Gate -->|"否"| Report["报告具体错误、未运行项和边界"]
    Gate -->|"是"| Ready["其他 Matt skills 可开始消费"]

Setup 产物

  • AGENTS.md 或 CLAUDE.md 中唯一的 ## Agent skills 区块。
  • docs/agents/issue-tracker.md：真实 Base/Wiki 坐标、命令、字段与身份合约。
  • docs/agents/triage-labels.md：仅当 triage 已安装时生成。
  • docs/agents/domain.md：单 context 或多 context 的领域文档规则。
  • Reuse 模式不创建 Base 字段/记录或 Wiki 文档；只读验证既有资源并生成 repo-local 合约。
  • Bootstrap 模式额外创建一份 Wiki setup 文档，记录实际命令、字段、状态机、失败与修正、验证证据。
  • Bootstrap 模式额外创建一条 setup POC Base 记录，链接 Wiki 文档并证明写路径闭环；它不是每个项目的必跑步骤。

7. to-spec：从对话到可执行规格

flowchart TD
    Context["对话 + 代码库 + Domain / ADR"] --> Seam["选择尽可能高的测试 seam"]
    Seam --> SeamConfirm{"用户确认 seam？"}
    SeamConfirm -->|"调整"| Seam
    SeamConfirm -->|"确认"| Draft["生成完整 Matt Spec"]
    Draft --> Search["按真实主字段精确查重"]
    Search --> Match{"精确匹配数量"}
    Match -->|"多个"| Disambiguate["停止并消歧"]
    Match -->|"一个，未明确修订"| Duplicate["停止并报告重复"]
    Match -->|"零个或明确修订"| CreateWiki["bot 在配置根节点下创建 Spec — 标题"]
    CreateWiki --> Append["append 完整 XML Spec"]
    Append --> Fetch{"docs +fetch 完整？"}
    Fetch -->|"否"| Stop["停止，不创建 Base"]
    Fetch -->|"是"| BaseSpec["创建或明确更新 Base Spec"]
    BaseSpec --> Parent["有来源 Issue 时写入所属父项"]
    Parent --> Readback["record-get 验证所有字段和最后更新人"]

Spec 产物契约

Wiki 文档标题为 Spec — <标题>，正文包含：Problem Statement、Solution、完整 User Stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes。

对应 Base 记录至少包含：

字段 值
产物类型 PRD/Spec
来源技能 to-spec
工作流阶段 规格
状态 ready-for-agent
协作模式 AFK
产物文档 Wiki Spec 链接
结论/摘要 Problem + Solution 摘要
验收标准 可执行、可验证条件
所属父项 可选的来源 Issue record ID
最后更新人 当前已验证 CLI 用户

8. to-tickets：从 Spec 到垂直切片依赖图

flowchart TD
    Spec["已确认 Spec / 计划"] --> Explore["可选：探索代码、prefactor 机会"]
    Explore --> Slice["拆成单上下文可完成的 tracer-bullet 垂直切片"]
    Slice --> Edges["为每张票声明真实 blocker"]
    Edges --> Quiz["用户确认粒度、合并/拆分和依赖边"]
    Quiz -->|"调整"| Slice
    Quiz -->|"批准"| ResolveParent["解析真实父 Spec record ID"]
    ResolveParent --> Search["逐标题查重；歧义时停止"]
    Search --> Pass1["第一遍：按依赖顺序创建全部 Ticket\n暂不写 blocker"]
    Pass1 --> IDs["保留每个返回的 record ID"]
    IDs --> Pass2["第二遍：写所属父项 + 前置依赖"]
    Pass2 --> Readback["逐条 record-get 验证父项、精确 blocker 集合、最后更新人"]
    Readback --> Frontier["frontier：所有 blocker 均完成且尚未认领的 Ticket"]

每个 Ticket 是一条 Base 记录；V1 不创建独立 Wiki 文档。Ticket 的 产物文档留空，实现者沿 所属父项找到父 Spec，再取得其 Wiki 文档。

普通垂直切片

flowchart LR
    A["Ticket A\n完整可验证切片\n无 blocker"] -->|"解锁"| B["Ticket B\n消费 A 的稳定输出"]
    B -->|"解锁"| C["Ticket C\n继续扩展端到端行为"]

Wide refactor 的 expand–migrate–contract

flowchart LR
    Expand["Expand\n新旧形式并存"] --> M1["Migrate batch 1"]
    Expand --> M2["Migrate batch 2"]
    Expand --> M3["Migrate batch N"]
    M1 --> Contract["Contract\n删除旧形式"]
    M2 --> Contract
    M3 --> Contract
    M1 --> Integrate["可选：integrate-and-verify"]
    M2 --> Integrate
    M3 --> Integrate

9. triage：Issue / PR 分诊与可恢复上下文

关注队列

每次“显示需要关注的事项”都必须完整分页，并按创建时间从旧到新汇总三类：

  1. 状态为空或待分诊。
  2. 状态=needs-triage。
  3. 状态=needs-info且本地比较得到最后反馈时间 > 最后分诊时间。

不能用单页查询宣称“没有待处理事项”。报告人活动只更新时间，不直接改变状态；后续 triage run 再根据时间门禁重启分诊。

Triage 状态机

stateDiagram-v2
    [*] --> 待分诊
    待分诊 --> NeedsTriage: 初次进入维护者评估
    state "needs-triage" as NeedsTriage
    state "needs-info" as NeedsInfo
    state "ready-for-agent" as ReadyAgent
    state "ready-for-human" as ReadyHuman

    NeedsTriage --> NeedsInfo: 信息不足
    NeedsInfo --> NeedsTriage: 报告人有新反馈\n且反馈时间晚于分诊时间
    NeedsTriage --> ReadyAgent: 事实充分且可委派
    NeedsTriage --> ReadyHuman: 需要人类判断、权限或手工工作
    NeedsTriage --> wontfix: 不实施

    ReadyAgent --> 进行中: Agent 认领
    ReadyHuman --> 进行中: 人类认领
    进行中 --> 待评审
    待评审 --> 已完成
    wontfix --> [*]
    已完成 --> [*]

每个已分诊项必须恰好拥有：

  • 一个类别：bug或enhancement。
  • 一个 canonical triage 状态。

推荐阶段只读、不写飞书；维护者确认后才更新类别、状态、时间、摘要、证据和下一步。

Outcome 与叙述产物

flowchart TD
    Outcome{"维护者确认的 outcome"}
    Outcome -->|"needs-info"| Notes["Wiki 追加 Triage Notes\n已确认事实 + 具体问题"]
    Outcome -->|"ready-for-agent"| Agent["Wiki 追加完整 Agent Brief"]
    Outcome -->|"ready-for-human"| Human["Wiki 追加 Human Brief\n注明不能委派原因"]
    Outcome -->|"wontfix"| Close["Wiki 追加关闭原因"]

    Notes --> Fetch["fetch 最新 section"]
    Agent --> Fetch
    Human --> Fetch
    Close --> Fetch
    Fetch --> BasePatch["更新 Base 状态、产物文档、证据、下一步、时间、最后更新人"]

    Outcome -->|"拒绝 enhancement"| OOS["repo .out-of-scope/<concept>.md\n唯一决定事实来源"]
    OOS --> CodeRef["Base 代码引用保存 repo 路径"]
    Outcome -->|"已实现请求或拒绝 bug"| NoOOS["不写 .out-of-scope/"]

所有 AI 生成的 triage 文档 section 必须带免责声明。一个 Issue 只复用一份 Triage — <标题> dossier，后续 append，不为每个状态新建文档，也不覆盖历史。

10. 主执行状态机

stateDiagram-v2
    [*] --> 草拟中
    草拟中 --> 待确认
    待确认 --> ReadyAgent: 可由 Agent 独立执行
    待确认 --> ReadyHuman: 需要人类处理
    state "ready-for-agent" as ReadyAgent
    state "ready-for-human" as ReadyHuman

    ReadyAgent --> 进行中: 设置负责人并认领
    ReadyHuman --> 进行中: 人类认领
    进行中 --> 阻塞: 出现 blocker
    阻塞 --> 进行中: blocker 已解除
    进行中 --> 待评审
    待评审 --> 进行中: 评审要求修改
    待评审 --> 已完成: 验证证据充分

    草拟中 --> 已取代: POC 或被新方案替代
    待确认 --> 已取代
    ReadyAgent --> 已取代
    进行中 --> 已取代

    已完成 --> [*]
    已取代 --> [*]

状态一致性规则：

  • 状态=阻塞时，阻塞原因和下一步必须非空。
  • 设置已完成前必须有具体验证证据；无法验证时写“未运行”及原因。
  • POC、废弃版本和超越记录进入已取代，不删除审计证据。
  • 完成度、下一步和阻塞原因必须与状态一致。

11. 产物与关系模型

flowchart LR
    External["外部 Issue / PR / 表单"] -->|"来源链接、外部编号、报告人"| Issue["Base：需求/Issue"]
    Issue -->|"产物文档"| TriageDoc["Wiki：Triage dossier"]

    Spec["Base：PRD/Spec"] -->|"所属父项"| Issue
    Spec -->|"产物文档"| SpecDoc["Wiki：Spec — 标题"]

    TicketA["Base：实现 Ticket A"] -->|"所属父项"| Spec
    TicketB["Base：实现 Ticket B"] -->|"所属父项"| Spec
    TicketB -->|"前置依赖"| TicketA

    TicketA -.->|"沿父项取得文档"| SpecDoc
    TicketB -.->|"沿父项取得文档"| SpecDoc

    Issue -->|"代码引用"| RepoDecision["Repo：代码 / ADR / .out-of-scope/"]
    TicketA -->|"代码引用、验证证据"| Code["分支 / commit / PR / 测试"]
    TicketB -->|"代码引用、验证证据"| Code

哪个系统保存什么

信息 事实来源 原因
当前状态、类别、负责人、进度、时间 Base 可筛选、排序、聚合和自动化
父子关系、阻塞关系 Base link 字段 可计算 frontier，不依赖文字解析
Spec、Triage Notes、Agent/Human Brief Wiki / Docs 长文档可读、可追加、可审计
实现代码、测试、ADR、领域上下文 repo 与版本控制一致
被拒绝 enhancement 的持久决定 repo .out-of-scope/ 避免 Wiki 与 repo 产生两份决定事实
命令、测试结果、回读事实 Base 验证证据，必要时 Wiki 详述 完成状态必须可核验

12. 身份与“最后更新人”

sequenceDiagram
    participant H as 真实用户
    participant C as Codex / 工作流
    participant A as lark-cli auth
    participant B as Feishu bot
    participant T as Base record

    H->>C: 确认外部写入
    C->>A: auth status --json --verify
    A-->>C: bot verified + user verified + user.openId
    C->>C: 冻结 CURRENT_USER_OPEN_ID
    C->>B: --as bot 创建或更新记录
    B->>T: payload 包含最后更新人 = user.openId
    T-->>C: ok:true + record ID
    C->>T: record-get 回读
    T-->>C: 最后更新人显示真实用户

这是一条业务审计契约，而不是飞书 UI 的系统“最后操作者”字段：

  • 写入执行者：bot。
  • CLI 工作流真实发起者：最后更新人。
  • 当前工作责任人：负责人。
  • 每一次 Base create/update 都刷新最后更新人，包括仅修改状态、时间、关系、文档链接、证据或终态的 patch。
  • schema、view 和纯读操作没有行级归因目标，不写该字段。

13. Base 完整字段字典（29 个）

以下内容来自 2026-07-26 的实时 field-list 回读。

# 字段 Field ID 类型 / 取值 含义与使用规则
1 文本 fldzLHLTca text，主字段 记录的业务标题；Spec/Ticket 查重使用真实主字段精确匹配。
2 产物类型 fldlwQ46Ks single select：需求/Issue、PRD/Spec、实现 Ticket、Wayfinder Map、决策 Ticket、原型、研究、Handoff、ADR、领域词汇、Bug 诊断、代码评审、架构候选、教学资产 标识这条记录代表哪一种 Matt 工作流核心产物。
3 来源技能 fldUMyVtoS multi-select：setup-matt-pocock-skills、grill-with-docs、grill-me、triage、diagnosing-bugs、wayfinder、to-spec、to-tickets、implement、tdd、code-review、improve-codebase-architecture、domain-modeling、prototype、research、handoff、teach 记录创建或推进该产物的逻辑 Matt skills；使用逻辑流程名，不使用 Feishu 适配器后缀。
4 工作流阶段 fldjAkNPqD single select：探索/澄清、决策、规格、拆票/规划、实现、验证/评审、交付、维护/学习、分诊 产物当前处于端到端流程的哪个阶段；与状态是两个维度。
5 状态 fldHjFrlwJ single select：草拟中、待确认、待分诊、needs-triage、needs-info、ready-for-agent、ready-for-human、进行中、阻塞、待评审、已完成、wontfix、out-of-scope、已取代 全流程统一状态机；英文值保留 Matt triage canonical role 名称。
6 类别 fldQWuceDX single select：bug、enhancement Triage category role；每个被分诊项必须且只能有一个。
7 决策票类型 fldFpkeDkj single select：research、prototype、grilling、task Wayfinder 子决策票的处理方式；非决策票通常留空。
8 协作模式 fldVwgWNRU single select：HITL、AFK HITL 表示人类需要实时参与；AFK 表示 Agent 可独立推进。
9 优先级 fldJv2ts2l single select：P0、P1、P2、P3 表示业务/执行优先级；与依赖 frontier 分开管理。
10 负责人 fldGlPa1B1 user，单值 当前直接执行责任人；必须使用真实飞书用户，不用纯文本姓名或 bot 代替。
11 最后更新人 fld6nvDu18 user，单值 最近一次通过 lark-cli 创建或更新该记录的真实人类用户；不代表飞书 UI 的 API 操作者。
12 完成度 fldqNJjr0g number/progress，0–100% 执行进度；需与当前状态保持一致。
13 产物文档 fldorpkrbf text/plain 该记录的 canonical Wiki/长文档链接；Spec 和 Triage dossier 使用，V1 Ticket 留空。
14 验收标准 fldwbSY2pq text 可验证完成条件；实现 Ticket 必填，Spec 保存主要测试/验收条件。
15 验证证据 fldIQ0NQPO text 实际命令、测试结果、复现、评审或 read-back 事实；终态的重要门禁。
16 结论/摘要 fldmdDUJHh text 决策结论、规格摘要、诊断根因、研究摘要或交付结果；长分析放 Wiki。
17 阻塞原因 fldUsFDsTS text 仅阻塞或needs-info时填写；说明当前为何不能继续。
18 下一步 fldMY6XATm text 解除阻塞或进入下一阶段所需的最小、直接动作。
19 代码引用 fldNylIQ5y text 分支、commit、PR、文件路径、review fixed point 或 .out-of-scope/ 路径。
20 截止时间 fldZP6Cm30 datetime，yyyy-MM-dd HH:mm 人工承诺的截止时间；不是自动推算时间。
21 创建时间 fldnPF52hP created_at，只读 飞书自动记录的行创建时间；关注队列按此从旧到新排序。
22 更新时间 fldd3rTk0I updated_at，只读 飞书自动记录的行更新时间；与业务归因字段不同。
23 所属父项 flduS0iiPy self-link，双向 Spec 指向来源 Issue、Ticket 指向父 Spec、决策 Ticket 指向 Wayfinder Map；写入真实 record ID。
24 前置依赖 fldYkwZVu1 self-link，双向 指向阻塞当前项的记录；所有依赖完成后当前项才进入 frontier。
25 来源链接 fldp4F1S6m text/url 原始 Issue、PR、表单或外部系统 URL。
26 外部编号 fldpv8O5OW text 原始外部系统编号；不能当作 Base record ID 使用。
27 报告人 fld37AxlZf text 报告人显示名或外部标识；兼容报告人不是飞书用户的场景。
28 最后反馈时间 fldTwNj5Uz datetime，yyyy-MM-dd HH:mm 报告人或外部来源最近一次新增反馈的时间。
29 最后分诊时间 fldNy9eAgM datetime，yyyy-MM-dd HH:mm 维护者最近一次确认并写回分诊结果的时间；与反馈时间比较决定 needs-info 是否重入队列。

Link 字段边界

所属父项和前置依赖是自动化写入的正向事实来源。lark-cli 1.0.76可能返回同表双向关系的反向 field ID，但反向字段不一定能独立列出；在 CLI 明确回读证明前，不假设反向字段可以直接寻址。

14. 关键 CLI 操作模式

# 身份门禁
lark-cli auth status --json --verify

# Schema 与记录
lark-cli base +field-list --base-token <BASE_TOKEN> --table-id <TABLE_ID> --limit 200 --as bot --format json
lark-cli base +record-search --base-token <BASE_TOKEN> --table-id <TABLE_ID> --keyword "<TITLE>" --search-field <PRIMARY_FIELD> --as bot --format json
lark-cli base +record-upsert --base-token <BASE_TOKEN> --table-id <TABLE_ID> --json '<FIELD_MAP>' --as bot --format json
lark-cli base +record-upsert --base-token <BASE_TOKEN> --table-id <TABLE_ID> --record-id <RECORD_ID> --json '<PATCH>' --as bot --format json
lark-cli base +record-get --base-token <BASE_TOKEN> --table-id <TABLE_ID> --record-id <RECORD_ID> --as bot --format json

# Wiki / Docs
lark-cli wiki +node-create --space-id <SPACE_ID> --parent-node-token <ROOT_NODE_TOKEN> --obj-type docx --title "<TITLE>" --as bot --format json
lark-cli docs +update --doc <OBJ_TOKEN> --command append --content @artifact.xml --doc-format xml --as bot --format json
lark-cli docs +fetch --doc <OBJ_TOKEN> --detail with-ids --as bot --format json

共同约束：

  • record-upsert不会按业务标题自动去重；创建前必须查重。
  • link CellValue 必须使用真实 record ID，不能填标题或 Ticket 编号。
  • 文档先成功 fetch，再把 Wiki 链接和相应状态写入 Base。
  • 所有记录 create/update payload 都包含最后更新人。
  • 失败后不改用 user 身份，也不改到 Drive 或其他 Wiki 位置。

15. 已完成的真实 POC

应用身份全流程 POC

  • bot 成功在指定 Wiki 根节点下创建独立 Spec 与 Triage 文档。
  • Wiki 创建结果返回正确的parent_node_token、space_id和自动用户权限。
  • Base 成功创建 Spec、两张 Ticket 和一条 Issue。
  • Ticket 父项和 blocker 边可回读。
  • Issue 完成needs-info → reporter feedback → ready-for-agent时间门禁。
  • 四条 POC Base 记录验收后均标记为已取代，Wiki 文档保留审计证据。

最后更新人 POC

产物 Base record ID 最终验证
Spec recvqrDi2D3ky9 bot 创建；最后更新人=于选辉；状态已取代
Ticket A recvqrDoAyemKF 父项指向 Spec；归因正确；状态已取代
Ticket B recvqrDoAyBBZB 父项指向 Spec；前置依赖仅指向 Ticket A；归因正确；状态已取代
Issue recvqrDxnqoNUJ 完整 triage 状态流、时间门禁、Wiki Agent Brief、归因均通过；状态已取代

相关文档：

16. 当前验证状态与边界

  • Base schema 实时回读：29 个字段，产物文档唯一存在。
  • Wiki 根节点完整分页：5 个直属子文档，has_more=false。
  • 双身份验证：bot 和 user 均为 verified。
  • 四个新 skill 均有agents/openai.yaml；受影响 skill 已通过quick_validate.py。
  • 所有相关本地 skill、Wiki 文档和当前 vault 中，已移除被替换字段名的旧引用。
  • Ticket V1 有意不创建 Wiki 文档；其长上下文来自父 Spec。
  • 负责人若无法解析为真实飞书用户就留空并报告，不能填 bot 或伪造数据。
  • 未验证的命令、状态或产物不能写成“已完成”；需明确标记“未运行”及原因。

17. 最小心智模型

flowchart LR
    Issue["Issue\n要解决什么"] --> Spec["Spec\n为什么与验收边界"]
    Spec --> Tickets["Tickets\n可独立交付的垂直切片"]
    Tickets --> Work["实现 / 测试 / 评审"]
    Work --> Evidence["验证证据"]
    Evidence --> Done["已完成"]

    Base["Base"] -.->|"管理状态、关系、责任、时间"| Issue
    Base -.-> Spec
    Base -.-> Tickets
    Wiki["Wiki"] -.->|"保存 Spec 与 Triage 叙述"| Spec
    Repo["Repo"] -.->|"保存代码、测试、ADR、决定"| Work

一句话总结：Base 回答“现在是什么状态、由谁负责、依赖谁”，Wiki 回答“为什么这样做、具体要求是什么”，repo 回答“实现和验证事实是什么”；四个 Feishu skills 负责在三者之间建立可回读、可审计的连接。

Reference in New Issue View Git Blame Copy Permalink