obsidian-vault/docs/三阶段研发工作流产物链路与飞书 CLI 管理方案.md

# 三阶段研发工作流：产物链路、Skill 组合与飞书 CLI 管理方案

> 状态：研究与方案评审
>
> 日期：2026-07-28
>
> 范围：需求探索 → 需求转化 → 开发收口；Matt skills、Feishu Base/Wiki、`lark-cli` 与 Trellis 的产物衔接。
>
> 结论先行：三阶段方向成立，`Spec → Tickets → Start → Inline/Trellis → Close` 已有真实 POC 支撑；当前主要断点是探索阶段没有正式发布出口、`ready-for-agent` 与负责人分派之间断链、开发阶段缺少显式实现方法，以及 Wiki Spec 与 Trellis `prd.md` 的事实源边界尚未完全统一。来源 Issue 的后续状态由人类在 Base 中自行检查，不纳入自动化范围。

## 1. 研究问题与判断

本研究回答五个问题：

1. 三个阶段中每个 skill 实际负责什么，不负责什么？
2. 每个阶段必须产出什么，才能被下一阶段稳定消费？
3. 当前流程中的 `handoff`、原型、Spec、Tickets、Trellis artifacts 是否形成了单一、可追踪的链路？
4. 哪些环节已经经过真实 Feishu/Trellis POC，哪些仍是建议？
5. 如何在不把所有内容都复制进飞书的前提下，用 `lark-cli` 提升可查询性、恢复能力和审计性？

核心判断如下：

- `handoff` 是临时会话运输层，不是需求事实源，也不应是每一步必经的业务状态。
- `grill-me` 只负责消除决策歧义，不会自动生成需求文档；第一阶段缺少一个正式的“探索结论发布”动作。
- `prototype` 产出的是“回答一个问题的可运行原型”，不保证是 HTML。UI 问题可能产出浏览器多变体，逻辑问题应产出 TUI/状态模型。
- 第一阶段的文档应叫 **Discovery Brief（需求探索结论）**；第二阶段的 `to-spec` 才产出 **Engineering Spec（工程执行规格）**。二者不能都叫 PRD 并同时声称权威。
- `to-spec-feishu` 和 `to-tickets-feishu` 当前都不写 `负责人`，而 `start-work-feishu` 只查询当前用户负责的记录，存在明确的 Dispatch Gate 断链。
- `start-work-feishu` 只负责选择、路由、绑定和开始状态；`close-work-feishu` 只负责证据收口。中间必须存在 `standard implement`、`tdd`、诊断或评审等明确的方法 owner。
- 复杂探索更适合使用 `wayfinder` 的 Map + Decision Tickets，而不是用多份临时 `handoff` 串成长链。
- 飞书适合继续做管理控制面，不应复制完整 Trellis task 或 repo 内容。

## 2. 证据范围

### 2.1 本仓库总结文档

本研究以以下两篇总结为主：

- [Matt 工作流 × 飞书 CLI 全流程总结](<./Matt 工作流 × 飞书 CLI 全流程总结.md>)：覆盖 Setup、Spec、Tickets、Triage、29 字段、身份和 CLI 写后回读。
- [Matt 工作流 × 飞书 Skills × Trellis Coding 闭环总结](<./Matt 工作流 × 飞书 Skills × Trellis Coding 闭环总结.md>)：覆盖 Start、Inline/Trellis 路由、`1 Spec = 1 task`、Ticket 部分收口、Spec 最终收口和真实 POC。

两篇总结共同确认的事实源分工是：

| 事实 | 事实源 |
|---|---|
| 当前状态、负责人、父子、依赖、队列 | Feishu Base |
| Discovery、Spec、Triage 等长文档 | Feishu Wiki / Docs |
| 复杂开发的 planning、checkpoint、archive | Trellis |
| 代码、测试、ADR、领域词汇、实现证据 | repo |
| 选择、产品决策、Ticket review、Spec 最终 review | 人类 |

### 2.2 Skill 一手定义

本研究逐一核对了以下本地定义：

- `/Users/yuxuanhui/.agents/skills/grilling/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/grill-me/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/grill-with-docs/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/domain-modeling/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/handoff/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/prototype/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/prototype/LOGIC.md`
- `/Users/yuxuanhui/.agents/skills/prototype/UI.md`
- `/Users/yuxuanhui/.agents/skills/to-spec/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/to-spec-feishu/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/to-tickets/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/to-tickets-feishu/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/start-work-feishu/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/close-work-feishu/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/wayfinder/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/implement/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/tdd/SKILL.md`
- `/Users/yuxuanhui/.agents/skills/code-review/SKILL.md`

同时核对了飞书 tracker 的一手适配约定：

- `/Users/yuxuanhui/.agents/skills/setup-matt-pocock-skills-feishu/references/issue-tracker-feishu.md`
- `/Users/yuxuanhui/.agents/skills/to-spec-feishu/references/feishu.md`
- `/Users/yuxuanhui/.agents/skills/to-tickets-feishu/references/feishu.md`

### 2.3 Trellis 与 CLI 证据

Trellis 路由和产物规则来自：

- [Trellis × Matt 全局规则](<../AI-RD-Workflow/40-workflows/trellis-matt/CN/AGENTS.md>)
- [Trellis × Matt workflow](<../AI-RD-Workflow/40-workflows/trellis-matt/CN/workflow.md>)

本机只读验证：

```text
lark-cli --version
→ lark-cli version 1.0.76
```

当前 CLI 的 `base --help` 明确提供 Base records、views、dashboard、workflow、record history 和 data query；`docs --help`、`wiki --help`提供文档内容和知识库节点操作。`record-history-list` 是单条记录历史，不是整表审计；Workflow 创建后默认 disabled，启用应是单独动作。

Context7 命中的官方一手来源为 [`/larksuite/cli`](https://github.com/larksuite/cli)，其 README 确认 Lark CLI 采用 shortcut、API command、Universal API 三层调用，并为 Base、Docs、Wiki 等域提供版本匹配的 agent skills。

本研究没有写入 Feishu，也没有重新执行已有业务 POC。实际闭环证据沿用两篇总结中记录的“经销商政策”项目验证。

## 3. 推荐的总产物图

```mermaid
flowchart TD
    Issue["Base 需求/Issue<br/>稳定业务根 ID"] --> Discovery["Wiki Discovery Brief<br/>探索结论"]
    Issue --> Prototype["原型资产/结论<br/>HTML、应用路由或逻辑 TUI"]
    Issue --> Wayfinder["可选：Wayfinder Map"]
    Wayfinder --> Decision["Decision Tickets<br/>grilling / prototype / research / task"]

    Spec["Base PRD/Spec"] -->|"所属父项"| Issue
    Spec --> SpecDoc["Wiki Engineering Spec"]
    Tickets["Base 实现 Tickets"] -->|"所属父项"| Spec
    Tickets -->|"前置依赖"| Tickets

    Start["start-work-feishu"] --> Inline["Inline<br/>会话内冻结 IDs"]
    Start --> Trellis["Trellis task<br/>1 Spec = 1 task"]
    Spec --> Start
    Tickets --> Start

    Inline --> Repo["repo 代码 / 测试 / review 证据"]
    Trellis --> Repo
    Repo --> Close["close-work-feishu"]
    Close -->|"部分收口"| Tickets
    Close -->|"最终收口"| Spec
```

关系方向必须明确：

- Spec 的 `所属父项`指向来源 Issue。
- Ticket 的 `所属父项`指向 Spec。
- Decision Ticket 的 `所属父项`指向 Wayfinder Map。
- `前置依赖`保存真实 Base record ID，不保存标题或文本编号。

## 4. 第一阶段：需求探索

用户原设想：

```text
grill-me → handoff → prototype → handoff → grill-me
=> 需求文档 + HTML 一次性原型
```

方向合理，但需要把固定流水线改成按问题选路。

### 4.1 每个 skill 的实际作用

| Skill | 作用 | 直接产物 | 不负责 |
|---|---|---|---|
| `grill-me` | 包装 `grilling`；一次问一个产品/范围决策，并给推荐答案 | 当前会话中的共同理解 | 自动写 PRD、自动发布飞书、替用户做决策 |
| `handoff` | 跨 session/agent 传递恢复所需指针和下一步 | OS 临时目录中的 Markdown | 长期事实源、需求审批、业务状态 |
| `prototype` | 用一次性代码回答一个 UI、状态或数据形状问题 | UI 多变体，或逻辑 TUI/纯模块；运行方式；问题与 verdict | 默认 HTML、生产实现、完整需求文档 |
| 第二次 `grill-me` | 针对使用原型后出现的新冲突，确认 winner 和边界 | Prototype verdict、修订后的产品决策 | 从头重做采访、自动综合文档 |

`grilling` 明确要求环境可查的事实应直接查，不应反问用户；属于用户的决策才逐项确认。`handoff` 明确写到 OS 临时目录，并要求引用已有 artifacts，不复制其正文。这两点决定了 handoff 只能是运输层。

### 4.2 Prototype 不应等同于 HTML

`prototype` 有两个完全不同的分支：

| 需要回答的问题 | 原型形态 |
|---|---|
| “这个页面应该长什么样？” | UI 分支：同一路由的 3 个左右结构差异明显的变体，使用 `?variant=`切换 |
| “这个状态模型/业务逻辑合理吗？” | Logic 分支：小型 TUI 驱动纯 reducer、state machine 或函数集合 |

因此第一阶段的正式产物名称应是“可运行一次性原型”，而不是无条件要求 HTML。

还有一个 brownfield 边界：UI skill 强烈偏好把变体嵌入现有页面，复用真实数据、auth、header/sidebar 和信息密度。如果是已有产品，完全不读代码库就制作独立 HTML，容易得到在真页面中不成立的方案。建议：

- greenfield 或纯概念演示：第一阶段可以制作独立 HTML。
- brownfield UI：第一阶段允许只读代码库并嵌入真实页面；或把 UI prototype 推迟到第二阶段。
- 逻辑/状态问题：不要为了满足“HTML”形式而绕过 Logic prototype。

### 4.3 三种合理组合

#### 简单探索：同一会话

```text
grill-me →（必要时 prototype）→ targeted verdict review → Discovery Brief
```

没有会话切换时省略两个 `handoff`。

#### 跨会话探索

```text
grill-me
→ 更新 canonical Discovery dossier
→ handoff（只带 record ID / URL / path / next question）
→ prototype
→ 更新 prototype question、asset、verdict
→ handoff
→ targeted verdict review
→ Discovery Gate
```

临时 handoff 即使丢失，也可以从 Base/Wiki/repo 指针恢复。

#### 多条相互依赖的不确定性

```text
Wayfinder Map：Destination = 通过 Discovery Gate
  ├─ grilling ticket（HITL）
  ├─ prototype ticket（HITL）
  ├─ research ticket（AFK）
  └─ task ticket（HITL / AFK）
```

Wayfinder 原生提供 Map、Decision Tickets、blocker、frontier 和 fog of war，更适合多会话探索。现有 29 字段已包含 `Wayfinder Map`、`决策 Ticket`和四种`决策票类型`，但 Wayfinder 尚不在六个已完成真实 Feishu POC 的 workflow skills 中；正式默认采用前应补一次 create/update/read-back POC。

### 4.4 第一阶段最终产物

第一阶段不建议产出第二份 PRD，建议产出：

#### A. Wiki `Discovery Brief — <标题>`

至少包含：

1. Problem、目标用户和期望结果。
2. 已确认的产品规则与用户决策。
3. 假设、证据、开放问题和明确延期问题。
4. 原型要回答的精确问题。
5. 原型运行方式、变体键或逻辑操作方式。
6. Prototype verdict：选了什么、为什么、拒绝什么。
7. 初步可观察验收语言，但不写模块、文件和实现设计。
8. Out of scope。
9. 来源 Issue、Prototype、Research、Wayfinder record IDs/URLs。
10. 人类确认时间和当前版本。

#### B. Base 根记录

```text
产物类型 = 需求/Issue
来源技能 = grill-me / prototype / research（按实际追加）
工作流阶段 = 探索/澄清
状态 = 草拟中 → 待确认 → ready-for-agent
产物文档 = Discovery Wiki URL
结论/摘要 = 一段式探索结论
验收标准 = Discovery Gate
下一步 = grill-with-docs / to-spec
```

#### C. 原型资产

- 简单探索：`原型` Base child record 指向 Issue，保存问题、运行方式、path/URL 和 verdict。
- Wayfinder 路径：优先把 prototype 作为 Decision Ticket 的 asset，避免再创建一份重复 Base 记录。
- 需要长期复现时，保存 `repo@commit:path`。commit/branch/发布都需要独立用户授权。
- 未获 Git 授权时，可以保存本地路径和内容 hash，但必须标注“仅同机可恢复”。
- 只有跨团队、需要独立审计的移交才创建 `Handoff` Base 记录；普通 session handoff 不进入业务表。

### 4.5 Discovery Gate

只有以下条件同时满足，第一阶段才可交给第二阶段：

- 问题、目标用户和期望结果明确。
- In scope / Out of scope 明确。
- 原型问题有 verdict，或明确记录“不需要原型”。
- 阻塞性产品决策为空。
- 开放风险已显式列出并有 owner/next step。
- 用户确认 Discovery Brief 代表当前共同理解。
- Base/Wiki 写入如已执行，已经 read-back。

## 5. 第二阶段：需求转化

用户原设想：

```text
grill-with-docs → to-spec → to-tickets
```

这条序列基本正确，但每一步应有不同问题域，避免第二次采访。

### 5.1 Skill 作用与产物

| Skill | 输入 | 作用 | 产物 |
|---|---|---|---|
| `grill-with-docs` | Discovery Brief、prototype verdict、代码库、现有 glossary/ADR | 只处理探索结论与现有代码/领域模型的碰撞；校正术语；确认难逆技术决策 | `CONTEXT.md` 术语更新；少量 ADR；已确认工程约束 |
| `to-spec-feishu` | 已澄清上下文、代码库、领域词汇、ADR、来源 Issue、原型决策 | 不再采访；确认最高可用测试 seam；综合并发布 | Wiki `Spec — 标题` + Base `PRD/Spec`，状态 `ready-for-agent` |
| `to-tickets-feishu` | 已批准 Spec、代码库、切片和依赖 | 拆 tracer-bullet 垂直切片；让用户确认粒度与 blocker；两遍发布关系 | N 个 Base `实现 Ticket`，父项和依赖完整回读 |

`domain-modeling` 的边界需要保留：

- `CONTEXT.md`只保存稳定领域词汇，不复制 Spec。
- ADR 只用于难逆、反直觉且经过真实取舍的决策。
- 普通 task 细节继续留在 Discovery/Spec/Trellis，而不是推广成长期知识。

### 5.2 第一阶段如何成为第二阶段输入

建议 `to-spec-feishu` 的输入 manifest 至少包含：

```text
requestRecordId
discoveryWikiUrl
prototypeRefs[]
researchRefs[]
wayfinderMapRecordId（可选）
repositoryRef
discoveryUpdatedAt / digest
```

现有 `to-spec` 已允许把原型中最能表达决策的 state machine、reducer、schema 或 type shape 精简后写入 Spec。工作 Demo 本身不应复制进 Spec。

当前 adapter 允许 Spec 关联来源 Issue，但没有强制读取 Issue 的 Discovery Wiki 和全部 prototype/research children。建议把“按来源 Issue 读取并核对探索包”加入 precondition，并在 Spec 的 Sources/Further Notes 中保存稳定 record IDs/URLs。

### 5.3 第二阶段最终产物

- repo：更新后的领域词汇和必要 ADR。
- Wiki：唯一 Engineering Spec 长文档。
- Base：一个 Spec record、N 个 Ticket records、完整 parent/blocker 图。
- 人类确认：测试 seam、Spec 内容、Ticket 粒度和依赖。
- 分派信息：owner、priority、collaboration mode，或明确进入“待分派”队列。

### 5.4 明确断点：Dispatch Gate

一手适配契约显示：

- `to-spec-feishu/references/feishu.md` 的 Spec 字段表没有`负责人`。
- `to-tickets-feishu/references/feishu.md` 的 Ticket 字段表也没有`负责人`。
- `start-work-feishu` 只查询`负责人=当前用户`的 Spec/Ticket，并要求保持 owner 不变。

因此：

```text
ready-for-agent ≠ 已分派 ≠ 可被 start-work 查询
```

当前最小方案：

1. 建立 Base “待分派”视图：`状态=ready-for-agent AND 负责人为空`。
2. 人类在 Base UI 分派 owner、priority 和 collaboration mode。
3. `start-work-feishu` 只消费已分派队列。

CLI 化的两个可选演进：

- 新增轻量 `dispatch-work-feishu`：列出未分派 frontier，用户选择 owner，精确 patch 并 read-back。
- 扩展 `start-work-feishu` 支持“未分派且无 blocker”的自助认领，在同一次“选择并开始”确认中原子写 owner + in-progress；它不能认领已分派给他人的工作。

管理者分派和开发者自助认领都需要，不能只实现其中一种。

### 5.5 Spec Gate 与 Ticket Gate

Spec Gate：

- Discovery 来源完整。
- 测试 seam 已确认。
- Wiki 内容 fetch 完整。
- Base Spec 的 type/status/parent/link/acceptance 已 read-back。

Ticket Gate：

- 每张 Ticket 是单上下文可验证的垂直切片。
- 用户确认粒度、拆合和依赖。
- 父项与精确 blocker set 已逐条 read-back。
- 无 orphan Ticket。
- 进入 Dispatch Gate，而不是假设已经能 Start。

## 6. 第三阶段：开发与收口

用户原设想：

```text
start work → trellis / inline → close work
```

建议展开为：

```text
Dispatch Gate
→ start-work-feishu
  ├─ Inline
  │   → standard implement / tdd / diagnose
  │   → full-diff review + acceptance evidence
  │   → Ticket partial close ↔ continue
  │   → Spec final close
  └─ Trellis
      → bind/create planning task
      → snapshot/delta review
      → Base start patch + read-back
      → task.py start
      → standard implement / tdd
      → checkpoint + full-diff review
      → Ticket partial close ↔ continue
      → archive + status=completed
      → Spec final close
```

### 6.1 各角色的边界

| 角色/skill | 负责 | 不负责 |
|---|---|---|
| `start-work-feishu` | 查询、选择、刷新、路由、Inline 冻结或 Trellis mapping、开始 patch | 实现代码、完成 Ticket、初始化不存在的 Trellis |
| Inline | 小、明确、单上下文的生命周期选择 | 具体工程方法 |
| Trellis | 跨会话 planning、checkpoint、archive、`1 Spec = 1 task` | 替代 Spec、决定 Ticket 已完成 |
| `standard implement` / `tdd` | 实际编码和验证方法 | Base 状态和最终业务授权 |
| `code-review` / 主会话 acceptance check | 对完整 diff 做 Standards/Spec 检查 | 替代人类产品 review |
| `close-work-feishu` | 证据映射、Ticket 部分收口、Spec 最终收口、幂等对账 | 实现缺失代码、代替用户 review、代替 archive |

`implement` 原 skill 中的无条件 commit 与当前本机规则冲突；在 Trellis × Matt workflow 中已经被覆盖。commit、push、PR 仍分别需要用户明确授权。

### 6.2 Trellis 与 Wiki Spec 的事实源冲突

当前总结把 Wiki Spec 定义为叙述事实源，而 Trellis workflow 又把 `prd.md`称为 task-level spec source of truth。如果不分层，实施中修改 Trellis `prd.md`可能产生第二份业务 Spec。

建议统一为：

| 范围 | 权威来源 |
|---|---|
| 已批准的产品需求与验收 | Wiki Engineering Spec |
| 当前业务状态和关系 | Base |
| 当前实现批次的执行基线、技术计划和 checkpoint | Trellis `prd/design/implement` |
| 实现结果 | repo |

Trellis mapping 应增加或明确维护 `specUpdatedAt`/digest。发现 Wiki/Base Spec 变化时：

1. 停止使用旧 snapshot。
2. 重新读取并确认变更。
3. 刷新 Trellis artifacts。
4. 只 review delta。

不要让 Trellis 反向静默覆盖 Wiki，也不要双向自动同步长文档。

### 6.3 Trellis planning review 不应重复审全文

Trellis workflow 要求 planning artifacts 在 `task.py start` 前完成 review，而现有 `start-work-feishu` 在 artifact persistence 后可以直接写 Base 并 start；总结中的真实 POC还记录了一次 planning review 豁免。

更高效的门禁是：

- Feishu Spec/Tickets 已经完成用户 review，Trellis 只是忠实 snapshot：做自动一致性检查和 start confirmation，不重新 grill 全文。
- Trellis 新增了 Spec 中没有的技术决策、兼容策略、rollout/rollback 或重大执行取舍：只对新增 delta 做 `grill-with-docs` review，再 start。
- Artifact persistence 或 mapping read-back 失败：不写 Base。

这既关闭了 workflow 规则缺口，也避免重复审批。

### 6.4 Close 实际是循环，不是一次动作

`close-work-feishu` 有三个 route：

1. Ticket 部分收口。
2. Spec 最终收口。
3. 失败后的幂等对账。

Ticket 可以在 Trellis task 尚未 archive 时逐张完成。父 Spec 只有在以下门禁全部通过后才能完成：

- 所有 child Tickets 恰好为`已完成`。
- 每条 Spec acceptance 都有直接证据。
- 用户完成 Spec 最终 review。
- Trellis 路径的 task 已 archive 且 `status=completed`。
- 没有 Ticket write/read-back failure。
- 用户单独确认 Spec-only patch。

`task.py finish`只解除当前 session 指针，不能替代 archive 或 Base closure。

### 6.5 第三阶段最终产物

- repo：代码、测试、必要文档、真实命令结果、完整 diff review。
- Inline：冻结的 Spec/Ticket IDs 和当前会话证据；跨会话时必须重新按 ID 选择。
- Trellis：mapping、planning artifacts、checkpoint、archive task。
- Base Tickets：每张 Ticket 的验收映射、验证证据、代码引用和终态 read-back。
- Base Spec：最终验收证据、最终人类 review、终态 read-back。
- 来源 Issue：保留与 Spec 的父子关系供人类追踪；其状态由人类在 Base 中按需检查。

当前 `close-work-feishu` 关闭到 Spec 为止，不自动关闭或报告来源 Issue。此边界视为有意设计，不作为自动化断点。

## 7. 跨阶段传递性总表

| 阶段 | 最终产物 | 稳定身份/位置 | 下阶段如何消费 | 当前成熟度 |
|---|---|---|---|---|
| Setup（一次性） | tracker contract | repo `docs/agents/issue-tracker.md` | 所有 Feishu skills 读取 | 已验证 |
| 探索 | Base Issue + Wiki Discovery Brief | Issue record ID + Wiki URL | `grill-with-docs`、`to-spec` | 缺正式探索发布 adapter |
| 原型决策 | Prototype record/decision ticket + asset + verdict | record ID、path/branch/URL | Spec 的 Decisions/Sources | schema 已支持，发布 POC 待补 |
| 复杂探索 | Wayfinder Map + Decision Tickets | Map/Ticket record IDs | Discovery Gate 汇总 | skill 已有，Feishu POC 待补 |
| 领域转化 | `CONTEXT.md` + 必要 ADR | repo path/commit（如获授权） | Spec 使用词汇与决策 | 已有 skill |
| 工程规格 | Wiki Spec + Base Spec | Spec record ID + Wiki URL；parent=Issue | Tickets、Start、Trellis snapshot | 已真实 POC |
| 实施计划 | Base Tickets + dependency graph | Ticket IDs；parent=Spec；blocker IDs | Start 计算 frontier；Close 逐票验收 | 已真实 POC |
| 分派 | owner/priority/mode | Base fields | 进入当前用户 Start 队列 | **当前断点** |
| Inline 执行 | 会话冻结 IDs + repo 证据 | record IDs、diff/test refs | Close | 已设计；跨会话需重选 |
| Trellis 执行 | mapping + artifacts + checkpoint | task path + `meta.feishuTracker` | Close 解析 Spec、证据和 archive | 已真实 POC |
| Ticket 收口 | evidence/code refs + terminal read-back | Ticket record ID | 解锁下一 frontier | 已真实 POC |
| Spec 收口 | 全 Ticket、acceptance、review、archive、read-back | Spec record ID | 阶段交付完成；来源 Issue 由人类按需处理 | 已真实 POC |

## 8. 组合场景建议

| 场景 | 推荐组合 |
|---|---|
| 简单、无重大不确定性的需求 | `grill-me → Discovery Brief → grill-with-docs → to-spec → 少量 Tickets/直接 Start` |
| Greenfield UI 探索 | `grill-me → 静态 HTML 多变体 → verdict review → Discovery Brief` |
| Brownfield 页面调整 | `grill-me → 只读代码库 → 在真实路由做 UI variants → verdict → to-spec` |
| 状态机/业务逻辑不确定 | `grill-me → Logic TUI prototype → verdict → Spec 中吸收 decision-rich 状态模型` |
| 多会话、多条互相依赖的不确定性 | `Wayfinder Map → grilling/prototype/research/task frontier → Discovery Gate` |
| 外部 Issue/PR 进入 | `triage → needs-info/ready-for-agent → 必要时 Discovery/Spec → Tickets` |
| 小型已明确实现 | `start-work → Inline → standard implement → review → close` |
| 跨模块、长验收链 | `start-work → Trellis → delta review → implement/checkpoint → partial close → archive → final close` |
| 用户明确要求 test-first | `to-spec 确认公开 seam → TDD mode → vertical red/green slices → review → close` |

## 9. 更好的飞书 CLI 管理方案

### 9.1 保留四事实源，不做大一统同步

应继续坚持：

- Base 管“是什么状态、谁负责、依赖谁”。
- Wiki 管“为什么做、达成了什么共同理解”。
- Trellis 管“复杂执行如何恢复和归档”。
- repo 管“实际上实现和验证了什么”。

同步只传稳定 ID、版本、摘要、验收边界和证据指针。不要在 Base 复制全文，不要在 Trellis 复制业务状态，不要让 Wiki 保存一份代码侧事实副本。

### 9.2 现有 29 字段足以做 P0

P0 不建议先加字段。可以直接使用：

- `产物类型`
- `来源技能`
- `工作流阶段`
- `状态`
- `负责人`
- `最后更新人`
- `产物文档`
- `结论/摘要`
- `验收标准`
- `验证证据`
- `下一步`
- `代码引用`
- `所属父项`
- `前置依赖`

只有多个真实查询场景证明有价值时，才考虑新增多值`来源产物`或显式 version/digest 字段。

### 9.3 建议的 Base 视图/报告

| 视图/报告 | 条件或用途 |
|---|---|
| 探索中 | Issue/Wayfinder；阶段=探索/决策；状态=草拟/待确认 |
| 决策 frontier | Decision Ticket 未完成、未阻塞、未认领 |
| 待分派 | `ready-for-agent`且 owner 为空 |
| 我的可开始 | owner=当前用户且 blockers 全部恰好`已完成` |
| 进行中/阻塞 | 阻塞项必须有`阻塞原因`和`下一步` |
| 待评审 | Ticket 和 Spec 分组显示 |
| 待对账 | 写失败、read-back mismatch、Trellis archived 但 Base 未闭环 |
| 一致性异常 | 完成无证据、Ticket 无父项、Spec 完成但 child 未全完成、进行中但 owner 为空 |

Frontier 和一致性判断应由 CLI 完整分页后计算，不依赖第一页或肉眼判断。

### 9.4 Base Workflow 只做提醒，不做完成决策

当前 `lark-cli 1.0.76`支持 Base Workflow、views、record history 和 data query。推荐的自动化边界：

- 可以：状态变为待确认/待评审时通知 owner；未分派 ready item 超时提醒；阻塞项定期提醒。
- 不可以：因为测试通过、Trellis archive 或所有可见 Tickets 看似完成，就自动把 Spec 设为已完成。
- 不可以：用 Workflow 取代人类 review、写前重读和写后回读。
- Workflow 新建后保持 disabled；经过 dry-run/定义检查和用户确认后再单独 enable。

### 9.5 增加机器可读 tracker contract

当前 `docs/agents/issue-tracker.md`适合人读，但自动化需要解析自然语言。建议 Setup 稳定后同时生成：

```text
docs/agents/issue-tracker.md
docs/agents/issue-tracker.json
```

JSON 建议保存：

```text
schemaVersion
baseToken / tableId / viewIds / wikiRoot
semantic field key → field ID
enum values
completion gates
```

不保存 API credentials，也不保存固定个人 open ID；操作者身份仍在每次运行时通过 verified auth 解析。

### 9.6 抽机械 helper，不抽业务判断

六个 Feishu skills 已重复使用身份门禁、schema 验证、完整分页、record-ID patch、写前重读、写后回读、ignored-fields 检测和 batch reconciliation。可以在更多 POC 后抽取薄 helper：

```text
tracker auth-check
tracker contract-validate
tracker list-all
tracker patch-and-verify
tracker batch-patch-and-reconcile
tracker wiki-append-and-fetch
```

Helper 只包装当前 `lark-cli`并输出结构化 JSON/exit code。以下判断必须继续留在人类和 skill：

- 该问哪个产品问题。
- 谁应该负责。
- Inline 还是 Trellis。
- Ticket 是否满足验收。
- 是否允许关闭 Spec/Issue。

不要构建会自行推进全部状态的“大一统 Agent workflow”。

### 9.7 统一外部写入协议

所有 Feishu 记录写入继续遵守：

1. 读取 tracker contract。
2. 验证 bot 与当前人类 user，冻结本轮 user open ID。
3. 完整查询并用 record ID 定位。
4. 展示稳定 IDs 和精确 patch。
5. 用户确认外部写入。
6. 写前按 record ID 重读，发生漂移则确认失效。
7. 最小 patch；`负责人`和`最后更新人`语义分离。
8. 写后 `record-get`/完整分页回读。
9. 分别报告 updated、already synchronized、failed、mismatched。

Base record history 可用于单记录审计，但不能替代应用侧的全表一致性报告。

## 10. 推荐的 V2 主流程

```mermaid
flowchart TD
    Setup["一次性 Setup<br/>tracker contract"] --> Intake["创建/接收 Base Issue"]
    Intake --> Explore{"探索复杂度"}
    Explore -->|"简单"| Grill["grill-me"]
    Explore -->|"多会话/多决策"| Map["Wayfinder Map + Decision Tickets"]
    Grill --> Proto{"需要可运行反馈？"}
    Map --> Proto
    Proto -->|"UI"| UI["HTML / 真实路由多变体"]
    Proto -->|"Logic"| Logic["TUI / state model"]
    Proto -->|"否"| Brief
    UI --> Verdict["targeted verdict review"]
    Logic --> Verdict
    Verdict --> Brief["Discovery Brief + Discovery Gate"]

    Brief --> GWD["grill-with-docs<br/>只处理代码库碰撞与 durable decisions"]
    GWD --> Spec["to-spec-feishu<br/>Wiki Spec + Base Spec"]
    Spec --> Tickets["to-tickets-feishu<br/>vertical Tickets + blockers"]
    Tickets --> Dispatch["Dispatch Gate<br/>owner / priority / mode"]

    Dispatch --> Start["start-work-feishu"]
    Start -->|"Inline"| Impl["standard / tdd implementation"]
    Start -->|"Trellis"| Bind["bind + snapshot/delta review"]
    Bind --> Impl
    Impl --> Review["full-diff review + evidence"]
    Review --> Partial["close-work：Ticket 部分收口"]
    Partial -->|"仍有开放 Ticket"| Impl
    Partial -->|"全部完成"| Archive{"Trellis?"}
    Archive -->|"是"| TArchive["archive + status=completed"]
    Archive -->|"否"| Final
    TArchive --> Final["close-work：Spec 最终收口"]
```

流程不是不可逆直线：

- 第二阶段发现产品结论与代码事实冲突：回到 Discovery Brief，重新确认受影响决策。
- 开发中发现 Spec/acceptance 错误：回第二阶段修订 Spec/Tickets并重新 read-back。
- 只在实现偏离而需求正确时留在第三阶段修代码。
- 任何回退都更新 owning artifact，不依赖聊天摘要。

## 11. 落地优先级

### P0：先补断链，不改大架构

> 决策（2026-07-28）：实施以下 1–5；不增加来源 Issue 状态报告或聚合关闭，由人类在 Base 中自行检查。

1. 明确第一阶段产物叫 Discovery Brief，不叫第二份 PRD。
2. 把 `handoff` 从必经节点改成“发生 session 边界时才使用”。
3. 建立 Base “待分派”视图，补 Dispatch Gate。
4. 让 `to-spec-feishu` 显式读取来源 Issue、Discovery Wiki 和 prototype/research refs。
5. 为 Feishu-bound Trellis task 定义 snapshot/delta review，消除重复全文审批。

### P1：让复杂探索可管理

1. 为 Discovery/Prototype/Wayfinder 做一次真实 Base/Wiki create/update/read-back POC。
2. 增加 CLI 分派或 start self-claim 能力。
3. 建立探索、决策 frontier、待分派、待对账和一致性异常视图。

### P2：稳定后工程化

1. 生成机器可读 tracker JSON contract。
2. 抽取 `lark-cli` 机械 helper。
3. 多个真实查询证明需要后，再扩展`来源产物`或 version/digest schema。
4. 仅把提醒类流程沉淀为 Base Workflow，不自动做完成决策。

## 12. 最终评价

这套方案不需要推翻。它已经有一个很好的骨架：

```text
Issue → Spec → Tickets → Start → Inline/Trellis → Evidence → Partial/Final Close
```

真正需要调整的是五个语义：

1. `handoff` 是会话运输，不是业务产物。
2. Discovery Brief 是产品探索结论，不是 Engineering Spec。
3. 可运行原型不必然是 HTML。
4. `ready-for-agent` 不等于已分派，也不等于可以被 Start 查询。
5. Trellis 是执行基线和生命周期，不应成为第二份业务 Spec。

补上 Discovery 发布、Dispatch Gate、明确 implementation owner 和 Trellis delta review 后，三个阶段的产物就能形成可追踪、可恢复、可审计的闭环；来源 Issue 的后续状态继续由人类管理。