# 基于飞书的产物管理工作流

这套流程把需求澄清、规格、拆票、代码实现和收口串到飞书 Base/Wiki 与 Trellis 上。

本文以当前安装的 skill 名称为准：

- `setup-feishu` 指 `$setup-workflow-skills-feishu`；
- `start-feishu-work` 指 `$start-work-feishu`；
- `close-feishu-work` 指 `$close-work-feishu`；
- `to-sepc-feishu` 的正确名称是 `$to-spec-feishu`。

当前版本有三个明确边界：

1. Issue 不进入这套 Base；需求在进入 Base 前，通过对话、研究、原型或其他人工确认完成澄清。
2. 整个流程不再使用 `triage-feishu`，也不创建 Triage dossier、Agent Brief 或 Human Brief。
3. Base 只保留一个状态轴和 6 个状态，不再维护 `工作流阶段`。

## 事实源怎么分工

| 载体 | 负责保存 | 不负责保存 |
|---|---|---|
| 飞书 Base | Spec/Ticket 身份、项目、状态、负责人、父子关系、依赖、验收和验证摘要 | 大段需求正文、完整设计文档 |
| 飞书 Wiki / Docx | Engineering Spec、Map、研究、决策、长篇说明 | 可计算的工作队列和关系状态 |
| 代码仓库 | 代码、测试、ADR、领域文档和实现证据 | Base 当前状态 |
| Trellis | 多会话执行上下文、计划、源快照、归档证据 | 第二份 Spec 或 Ticket 主数据 |

几个始终有效的规则：

- Base 管状态和关系，Wiki 管长文，代码仓库管实现和验证。
- Trellis 只保存执行上下文，不能静默改写 Wiki Spec 或 Base Ticket。
- Feishu CLI 的 Base、Wiki、Docs 操作统一使用 `--as bot --format json`。
- API 由 bot 执行，但 `最后更新人` 必须写当前已验证用户。
- 每次写入都要回查，不能只看 `ok: true`。

# 一、初始化

## 1.1 初始化飞书 CLI

### 安装

官方推荐安装方式：

```bash
npx @larksuite/cli@latest install
```

安装后先确认实际版本：

```bash
command -v lark-cli
lark-cli --version
```

本文验证时使用的是 `lark-cli 1.0.76`。换机器或升级版本后，先查看当前版本和子命令 `--help`，不要直接照搬旧参数。

### 初始化应用身份

```bash
lark-cli config init --new
```

需要进入交互流程时可以使用：

```bash
lark-cli config init
```

注意：

- `app_secret` 不能写入文档、Trellis 产物或命令历史；
- 非交互环境优先使用 `--app-secret-stdin`；
- 如果当前环境已经绑定应用，先确认是否应使用 `lark-cli config bind`，不要未经确认创建平行应用。

### 登录用户身份

推荐登录：

```bash
lark-cli auth login --recommend
```

按业务域登录：

```bash
lark-cli auth login --domain base,docs,wiki
```

不能阻塞等待授权时，使用设备码：

```bash
lark-cli auth login --domain base,docs,wiki --no-wait --json
lark-cli auth login --device-code <DEVICE_CODE>
```

### 验证双身份

```bash
lark-cli auth status --json --verify
```

必须同时满足：

- `identities.bot.verified=true`；
- `identities.user.verified=true`；
- `identities.user.openId` 非空。

飞书操作由 bot 执行。用户 open ID 只用于查询当前用户的工作和填写 `最后更新人`，不能固化成全局配置。

最小检查：

```bash
lark-cli --version
lark-cli auth status --json --verify
lark-cli base --help
lark-cli wiki --help
lark-cli docs --help
```

官方入口：[Lark CLI README](https://github.com/larksuite/cli/blob/main/README.md)。

## 1.2 项目初始化：`setup-workflow-skills-feishu`

CLI 初始化解决“能不能访问飞书”，Setup 解决“这个仓库应该访问哪张 Base、哪个 Wiki 项目目录”。

```text
$setup-workflow-skills-feishu
```

### 提前准备的飞书内容

需要明确提供：

1. Base 表格或视图 URL；
2. Wiki 工作区根节点 URL；
3. 项目目录名称，或已有项目节点 URL。

还应提前确认：

- 一张用于管理 Spec、Ticket 和进度的 Base 表；
- 一个明确的 Base 视图；
- bot 可访问的 Wiki 知识空间；
- 一个已确认的项目名，项目名不必等于仓库名；
- bot 对 Base、Wiki、Docs 的应用权限和资源 ACL；
- 用户 OAuth 已完成，bot 和 user 都能通过验证。

推荐的 Wiki 层级：

```text
<WORKSPACE_ROOT>
├── 知识文档
└── 项目目录
    └── <PROJECT_NAME>
```

当前只使用以下路由，均指向项目节点：

| 路由 | 用途 |
|---|---|
| `setup` | 项目配置说明 |
| `spec` | Engineering Spec |
| `wayfinder` | Map 与决策文档 |

不再创建 `triage` 路由，也不把 `知识文档` 当作 skill 写入失败后的兜底位置。

### Setup 的两个独立选择

| 维度 | 推荐模式 | 可写模式 | 作用 |
|---|---|---|---|
| Tracker | Reuse tracker | Bootstrap tracker | 只读校验或补齐 Base 标准字段 |
| Project Binding | Reuse existing binding | Provision missing binding | 校验或创建 Wiki 项目目录，并补充项目选项 |

- **Reuse tracker**：只读检查 Base 坐标、字段和选项；不创建字段、不创建配置文档。
- **Bootstrap tracker**：经过确认后，只新增缺失字段并创建一份项目配置说明。
- **Reuse existing binding**：只读检查 Wiki 目录和 `所属项目` 选项。
- **Provision missing binding**：经过独立确认后，只创建缺失节点或追加缺失项目选项。

两个授权范围互不包含。字段修复不等于允许创建 Wiki 节点，项目目录授权也不等于允许改表结构。

### Setup 的产出

Setup 会留下：

- `CLAUDE.md` 或 `AGENTS.md` 中的 `## Agent skills` 区块；
- `docs/agents/issue-tracker.md`；
- `docs/agents/domain.md`；
- Bootstrap 模式下的缺失字段和项目配置说明文档；
- Provision 模式下的项目 Wiki 节点或项目选项。

不再生成 `docs/agents/triage-labels.md`。后续 Feishu skill 读取的是 `docs/agents/issue-tracker.md`，其中应记录契约版本、Base/Wiki 坐标、真实主字段、项目绑定、24 个字段、路由和可执行命令。

## 1.3 当前 Base 字段：24 个

旧契约有 30 个字段。根据当前流程，删除了 6 个：

- `工作流阶段`；
- `类别`；
- `外部编号`；
- `报告人`；
- `最后反馈时间`；
- `最后分诊时间`。

原因是 Issue 不进入 Base，triage 已移除，而且状态本身已经足够表达下一步动作。当前契约共 24 个字段：

| # | 字段 | 类型 / 典型值 | 含义与功能 |
|---:|---|---|---|
| 1 | 实际主字段 | 主字段文本 | 记录标题。创建前用于查重，更新必须使用 record ID。 |
| 2 | 产物文档 | 文本 / URL | Wiki Spec、Map 或其他长文产物的规范链接。 |
| 3 | 产物类型 | 单选 | `PRD/Spec`、`实现 Ticket`、`Wayfinder Map`、`决策 Ticket`、`原型`、`研究`、`Handoff`、`ADR`、`领域词汇`、`Bug 诊断`、`代码评审`、`架构候选`、`教学资产`。不再有 `需求/Issue`。 |
| 4 | 所属项目 | 单选，`multiple=false` | 项目边界。父项和依赖必须属于同一项目。 |
| 5 | 来源技能 | 多选 | 记录由哪个 skill 创建或维护，如 `to-spec`、`to-tickets`、`start-work`、`close-work`、`wayfinder`。不再包含 `triage`。 |
| 6 | 来源链接 | 文本 / URL | 当前对话、PR、表单、研究或外部系统的来源链接。 |
| 7 | 状态 | 单选 | 只允许 6 个状态：`ready-for-agent`、`进行中`、`阻塞`、`待评审`、`已完成`、`wontfix`。 |
| 8 | 决策票类型 | 单选 | `research`、`prototype`、`grilling`、`task`。 |
| 9 | 协作模式 | 单选 | `HITL` 或 `AFK`。表示执行过程中人工参与的强度，不替代状态。 |
| 10 | 优先级 | 单选 | `P0`—`P3`，用于排序和资源安排。 |
| 11 | 负责人 | 单用户 | 当前执行人。Start 不擅自覆盖。 |
| 12 | 最后更新人 | 单用户 | 最近一次通过 CLI 改动记录的真实操作者。 |
| 13 | 完成度 | 数字 / 百分比 | 进度量化，收口时写为 `1`。 |
| 14 | 验收标准 | 长文本 | 可观察、可验证的完成条件。 |
| 15 | 验证证据 | 长文本 | 实际命令、测试结果、回查事实和未运行项。 |
| 16 | 结论/摘要 | 长文本 | Base 中的简洁摘要；`wontfix` 的具体原因也写在这里。 |
| 17 | 阻塞原因 | 长文本 | `状态=阻塞` 时解释为什么不能继续。 |
| 18 | 下一步 | 长文本 | 解除阻塞或继续推进的明确动作。 |
| 19 | 代码引用 | 长文本 | 文件路径、分支、commit、PR、评审链接或 Trellis 证据。 |
| 20 | 截止时间 | 日期时间 | 业务期望完成时间。 |
| 21 | 创建时间 | 系统字段，只读 | 排序和审计。 |
| 22 | 更新时间 | 系统字段，只读 | 并发变更检测和源快照比较。 |
| 23 | 所属父项 | 同表关联 | Ticket → Spec，决策 Ticket → Map。 |
| 24 | 前置依赖 | 同表关联 | blocker 的真实 record ID，用于计算可执行 frontier。 |

### 6 个状态的含义

```text
ready-for-agent → 进行中 → 待评审 → 已完成
                         ↘ 阻塞 ↗

任一未完成状态 ─────────────→ wontfix
```

| 状态 | 含义 | 是否进入 Start 队列 |
|---|---|---:|
| `ready-for-agent` | 已澄清、可以交给 Agent 开始 | 是，前置依赖满足时可选 |
| `进行中` | 已认领，正在实现或恢复工作 | 是 |
| `阻塞` | 被依赖、决策或外部条件卡住 | 是，作为可恢复项展示 |
| `待评审` | 实现完成，等待人工评审和 Close | 否，转给 Close |
| `已完成` | 验收和人工确认完成 | 否 |
| `wontfix` | 不再交付；原因写入 `结论/摘要` | 否 |

`wontfix` 是唯一非交付终态。它不能满足其他 Ticket 的前置依赖；只有 `已完成` 才表示依赖交付。

---

# 二、需求澄清阶段

当前流程不再把需求先写成 Issue 再分诊。需求澄清发生在对话、研究、原型、grilling 或人工决策中；只有形成明确方案后，才写入 Spec/Ticket Base。

## 2.1 `to-spec-feishu`

```text
$to-spec-feishu
```

`to-spec-feishu` 使用已经形成的上下文，不重新访谈用户：

1. 读取当前对话、领域术语、代码库和 ADR；
2. 找到尽可能高层、数量尽可能少的测试 seam；
3. 让用户确认 seam 和 Spec 方向；
4. 生成 Problem Statement、Solution、User Stories、Implementation Decisions、Testing Decisions、Out of Scope 和 Further Notes；
5. 将完整 Spec 发布到 Wiki；
6. 创建关联的 `PRD/Spec` Base 记录。

发布顺序是先 Wiki、后 Base。Wiki fetch 回查正文完整后，才创建 Base 记录。

Base Spec 的初始值：

```text
产物类型 = PRD/Spec
状态 = ready-for-agent
协作模式 = AFK
产物文档 = Wiki Spec 链接
```

如果决定不再交付已经创建的 Spec，可以把它设为 `wontfix`，并在 `结论/摘要` 写明原因；这不是 triage，而是产物生命周期中的人工决策。

## 2.2 `to-tickets-feishu`

```text
$to-tickets-feishu
```

`to-tickets-feishu` 把已批准的 Spec 拆成 tracer-bullet 垂直切片：

- 每张 Ticket 穿过完成行为所需的各层；
- 单独完成后可演示或验证；
- 能在一个新上下文窗口内完成；
- 只声明真实的阻塞关系；
- 宽范围机械重构使用 `expand → migrate batches → contract`。

发布前必须让用户确认粒度、拆分和依赖。发布分两步：

1. 按依赖顺序创建全部 Ticket，保存真实 record ID；
2. 用 record ID 回写 `所属父项` 和 `前置依赖`，逐条回查。

每条 Ticket 的初始值：

```text
产物类型 = 实现 Ticket
状态 = ready-for-agent
协作模式 = AFK
所属父项 = 父 Spec record ID
前置依赖 = blocker record IDs
产物文档 = 留空
```

V1 不给每张 Ticket 单独建 Wiki 文档；Ticket 的切片事实保存在 Base，长文仍归属于父 Spec。

## 2.3 需求澄清的全部操作可能

```mermaid
flowchart TD
    A["当前对话、研究、原型或其他需求来源"] --> B{"是否已经有明确的目标、约束和验收？"}
    B -- "否" --> C["HITL：继续澄清、grilling 或补充研究"]
    C --> B
    B -- "是" --> D{"是否决定继续交付？"}
    D -- "否" --> E["不创建 Issue；若已有 Spec/Ticket，则设为 wontfix 并记录原因"]
    D -- "是" --> F["to-spec-feishu：发布 Wiki Engineering Spec"]
    F --> G["Base Spec：PRD/Spec + ready-for-agent"]
    G --> H{"是否需要多个独立垂直切片？"}
    H -- "否" --> I["直接进入 start-work-feishu"]
    H -- "是" --> J["to-tickets-feishu：起草 Ticket 和依赖图"]
    J --> K{"用户是否批准粒度和依赖？"}
    K -- "否" --> J
    K -- "是" --> L["创建 Ticket、回写父子关系和前置依赖"]
    L --> M["Spec + Tickets 进入开发队列"]
```

本阶段的正式产出只有：

- Wiki Engineering Spec；
- 一个 `PRD/Spec` Base 记录；
- 可选的多个 `实现 Ticket` Base 记录；
- 父子关系、依赖关系和可执行 frontier。

不再产出：

- `需求/Issue` Base 记录；
- Triage dossier；
- `needs-triage`、`needs-info`、`ready-for-human` 等状态；
- `类别`、`最后分诊时间` 等 triage 字段。

---

# 三、代码开发阶段

代码开发阶段由 `$start-work-feishu` 开始，由 `$close-work-feishu` 收口。Start 负责“选中并认领”，Close 负责“证据核验并关闭”。

## 3.1 `start-work-feishu`

```text
$start-work-feishu
```

### 功能

Start 会：

- 验证项目契约、双身份、Base 坐标和 24 个字段；
- 查询当前用户负责的 Spec 和 Ticket；
- 解析父项、依赖、负责人和更新时间；
- 把记录分为可开始、可恢复、被阻塞和待评审；
- 让用户选择具体 record ID；
- 推荐 Inline 或 Trellis；
- 经确认后把目标记录改为 `状态=进行中`，并回写 `最后更新人`。

它不会自动改负责人、完成度、兄弟 Ticket，也不会因为看到了 `ready-for-human` 而转派工作，因为当前状态机已经删除这个状态。

### 工作队列

| 条件 | 分类 | 是否可选 |
|---|---|---:|
| `进行中` | 可恢复 | 是 |
| `阻塞` | 可恢复，但展示阻塞原因 | 是 |
| `ready-for-agent`，无依赖或依赖全为 `已完成` | 可开始 | 是 |
| `ready-for-agent`，存在未完成依赖 | 被阻塞 | 否 |
| `待评审` | 待收口 | 否，转 Close |
| `wontfix`、`已完成` 或其他不匹配记录 | 不进入开发队列 | 否 |

只有 `已完成` 能满足依赖。`wontfix` 不是依赖完成证明。

选择 Spec 时只更新 Spec。选择 Ticket 时，同时更新 Ticket 和唯一父 Spec：

```text
状态 = 进行中
最后更新人 = 当前已验证用户
```

负责人、所属项目、完成度和未选中的兄弟 Ticket 保持不变。

### Inline 与 Trellis

适合 Inline：

- 范围窄，路径已知；
- 一个上下文可以完成；
- 验证命令能在当前会话运行。

适合 Trellis：

- 跨模块或多会话；
- 有多个稳定决策和交付物；
- 需要保存长验收链；
- 仓库已经有 `.trellis/`。

仓库没有 `.trellis/` 时，Start 不会自行初始化；需要用户单独授权后再初始化，或选择 Inline。

## 3.2 Start 如何承接 Trellis

### 一对一绑定

```text
1 个飞书 Spec = 1 个 Trellis task
```

Ticket 是该 task 内的计划和验收单元，不为每张 Ticket 创建独立 Trellis 子任务。直接选择 Ticket 时，也绑定到父 Spec 的同一个 task。

映射保存在：

```text
task.json.meta.feishuTracker
```

至少保存 `specRecordId`、`ticketRecordIds`、`selectedRecordIds`、`specWikiUrl`、`trackerContractPath`、`boundAt` 和 `lastRefreshAt`。映射里不保存凭证、Base token 或固定用户 ID。

### 创建和启动顺序

```bash
python3 ./.trellis/scripts/task.py create "<SPEC_TITLE>" \
  --slug "feishu-<NORMALIZED_SPEC_RECORD_ID>" \
  --description "Implement Feishu Spec <SPEC_RECORD_ID>" \
  --no-start
```

正确顺序：

1. 在 `prd.md` 维护飞书 Spec 来源区块；
2. 在 `implement.md` 维护 Ticket 快照；
3. 写入并回查 `task.json.meta.feishuTracker`；
4. 比较 Trellis 快照与飞书批准源；
5. 用户确认选择、路由、稳定 ID 和 Base patch；
6. 更新 Base 并回查；
7. Base 认领成功后启动 Trellis：

```bash
python3 ./.trellis/scripts/task.py start <TASK_DIR>
```

这样可以把失败范围控制在一个边界内：本地映射失败不碰 Base，Base 回查失败不启动 Trellis。

### 快照判定

| 判定 | 含义 | 动作 |
|---|---|---|
| `snapshot-only` | 只是已批准 Spec/Ticket 的忠实镜像 | 做机械一致性检查 |
| `delta-reviewed` | 新增实现顺序、兼容、迁移、安全或回滚决策 | 只评审新增技术差量 |
| `source-revision-required` | 改变产品行为、范围、验收或依赖语义 | 回到 Wiki/Base 修订正式源 |

Trellis 能补充执行计划，不能静默变更正式业务产物。

### Trellis 生命周期

| 命令 | 语义 |
|---|---|
| `task.py create --no-start` | 创建 `planning` 任务，不设为活动任务 |
| `task.py start <TASK_DIR>` | 将任务设为活动并改为 `in_progress` |
| `task.py finish` | 只清除当前会话活动指针，不代表完成 |
| `task.py archive <TASK_DIR> --no-commit` | 写入 `completed` 并移动到月度归档目录 |

Trellis 路线最终关闭 Spec 时，要求归档树下存在 `task.json` 且 `status=completed`。按本机约定，归档使用 `--no-commit`。

## 3.3 `close-work-feishu`

```text
$close-work-feishu
```

### 功能

Close 会：

- 从 Trellis 映射、归档 task 或 Inline 冻结 ID 解析 Spec；
- 每次重新查询全部子 Ticket；
- 从代码、测试、命令结果、Trellis 产物和 Base 记录收集直接证据；
- 将 Ticket 分为建议可收口、待补证/待验证、明确未完成/阻塞；
- 只关闭用户明确选择的 Ticket；
- Ticket 回查通过后，再判断 Spec 是否满足最终门禁；
- 需要时对部分成功的写入进行幂等重放。

Close 不补代码、不自动归档 Trellis，也不因为测试通过或 Agent 说“完成”就改变 Base 状态。

### Ticket 证据分类

| 分类 | 条件 | 默认动作 |
|---|---|---|
| 建议可收口 | 每条验收都有直接证据，且没有未解决阻塞 | 交给人审 |
| 待补证/待验证 | 可能已实现，但至少一条验收缺少直接证据 | 不关闭 |
| 明确未完成/阻塞 | 行为、依赖、决策、实现或验证仍未完成 | 不关闭 |

### Ticket 收口

用户必须明确两件事：

1. 代码和功能的人审已经完成；
2. 哪些 Ticket record ID 允许关闭。

选中的 Ticket 更新为：

```text
状态 = 已完成
完成度 = 1
阻塞原因 = 空
下一步 = 空
验证证据 = 保留原文并追加本次 closure 证据
代码引用 = 保留原文并追加去重后的真实引用
最后更新人 = 当前已验证用户
```

每条记录都按 ID 回查。未选择的 Ticket 保持原状。只要还有 Ticket 不是 `已完成`，Spec 就不能完成。

### Spec 最终收口

必须同时满足：

- 所有子 Ticket 恰好为 `已完成`；或没有 Ticket，但 Spec 自身验收已有直接证据；
- Spec 每条验收都有直接证据；
- 没有 Ticket 写入失败或回查不一致；
- 用户明确确认最终人审完成；
- Trellis 任务已归档且 `task.json.status=completed`；Inline 无此门禁。

Ticket 关闭确认不能自动授权 Spec 关闭。Spec 必须再展示一次独立 patch 并取得确认。

## 3.4 Start → Inline / Trellis → Close

```mermaid
flowchart TD
    A["start-work-feishu：验证身份、24 字段、Base 和队列"] --> B["用户选择 Spec 或 Ticket"]
    B --> C["刷新 record ID、父项、依赖、负责人和更新时间"]
    C --> D{"选择执行路由"}

    D -- "Inline" --> E["冻结 ID 和最新快照"]
    E --> F["确认选择、路由和 Base patch"]
    F --> G["Base：状态改为进行中并回查"]
    G --> H["当前会话实现、测试和整理证据"]

    D -- "Trellis" --> I{"已有唯一 Spec task？"}
    I -- "有" --> J["复用 task"]
    I -- "没有" --> K["create --no-start：planning"]
    I -- "冲突" --> L["停止并处理映射冲突"]
    J --> M["刷新 Spec 来源、Ticket 快照和映射"]
    K --> M
    M --> N{"快照判定"}
    N -- "snapshot-only" --> O["机械一致性检查"]
    N -- "delta-reviewed" --> P["评审新增技术决策"]
    N -- "source-revision-required" --> Q["回到 Wiki/Base 修订正式源"]
    Q --> M
    O --> R["确认选择、路由、判定和 Base patch"]
    P --> R
    R --> S["Base：状态改为进行中并回查"]
    S --> T["task.py start：planning → in_progress"]
    T --> U["多会话实现、测试、评审和证据"]
    U --> V["task.py archive --no-commit：completed"]

    H --> W["close-work-feishu：查询全部 Ticket 并收集证据"]
    V --> W
    W --> X["输出证据表和收口建议"]
    X --> Y{"人工评审并选择 Ticket"}
    Y -- "证据不足或未选择" --> Z["保留未完成记录并给出下一步"]
    Y -- "确认关闭" --> AA["更新所选 Ticket 并逐条回查"]
    AA --> AB{"全部 Ticket 完成且 Spec 验收满足？"}
    AB -- "否" --> AC["部分收口：Spec 保持进行中"]
    AB -- "是" --> AD{"Trellis 已归档？"}
    AD -- "未归档" --> AE["阻塞 Spec 收口；归档后重跑 Close"]
    AD -- "Inline 或已归档" --> AF["第二次人审：确认 Spec 最终关闭"]
    AF --> AG["更新 Spec 为已完成并回查"]
```

---

# 四、全流程总结

## 4.1 从初始化到收口

```mermaid
flowchart LR
    A["CLI 初始化"] --> B["Setup：解析 Base、Wiki 和项目"]
    B --> C["24 个字段 + 项目绑定 + spec/wayfinder 路由"]
    C --> D["HITL：对话、研究、原型和决策完成需求澄清"]
    D --> E["to-spec-feishu：Wiki Spec + Base PRD/Spec"]
    E --> F{"是否需要拆票？"}
    F -- "否" --> G["start-work-feishu：直接开始 Spec"]
    F -- "是" --> H["to-tickets-feishu：Base Tickets + 依赖图"]
    H --> I["start-work-feishu：选择 Spec 或 Ticket"]
    G --> J{"Inline / Trellis"}
    I --> J
    J --> K["代码、测试、评审和验证证据"]
    K --> L["close-work-feishu：关闭 Ticket"]
    L --> M{"Trellis 路线？"}
    M -- "是" --> N["确认 task 已归档"]
    M -- "否" --> O["跳过归档门禁"]
    N --> P["第二次人审：关闭 Spec"]
    O --> P
    P --> Q["Base、Wiki、代码和 Trellis 形成闭环"]
```

## 4.2 每个环节的产出

| 环节 | 主要输入 | 主要产出 | 事实源 |
|---|---|---|---|
| CLI 初始化 | 飞书应用、用户授权 | bot/user 双身份可验证 | Lark CLI 配置 |
| 项目 Setup | Base URL、Wiki 根 URL、项目名 | 24 字段契约、项目绑定、路由、`docs/agents/*` | Base + Wiki + Repo |
| 需求澄清 | 对话、研究、原型、人工决策 | 已批准的产品目标、约束和验收 | Conversation/Wiki |
| To Spec | 已澄清上下文、领域术语、测试 seam | Wiki Engineering Spec、Base `PRD/Spec` | Wiki + Base |
| To Tickets | 已批准 Spec | Base Ticket、父子关系、依赖图、frontier | Base |
| Start | 当前用户队列、record ID、依赖 | `进行中` 状态、Inline 上下文或 Trellis 映射 | Base + Conversation/Trellis |
| 实现 | Spec、Ticket、代码库、Trellis 计划 | 代码、测试、命令结果、验证证据 | Repo + Trellis |
| Close Ticket | 实时 Ticket、直接证据、人审选择 | Ticket `已完成` 或保留原状态 | Base |
| Trellis Archive | 已完成的多会话任务 | `status=completed` 和归档路径 | Trellis |
| Close Spec | 全部 Ticket、Spec 验收、最终人审 | Spec `已完成` | Base |

## 4.3 HITL 与 AFK 的边界

### HITL：必须有人拍板

| 环节 | 人工门禁 |
|---|---|
| Setup | 选择 Reuse/Bootstrap、Reuse/Provision，并确认具体外部写入 |
| 需求澄清 | 确认目标、范围、约束、验收和是否继续交付 |
| To Spec | 确认测试 seam 和正式 Spec |
| To Tickets | 确认 Ticket 粒度、拆分和阻塞边 |
| Start | 选择 record ID，确认 Inline/Trellis 和 Base patch |
| Trellis 差量 | 评审新增技术决策；影响产品行为时回到正式源 |
| Close Ticket | 确认代码/功能人审完成，并选择允许关闭的 Ticket |
| Close Spec | 在所有门禁满足后进行最终关闭确认 |

### AFK：确认后可以交给 Agent

- 校验 CLI 身份、Base 坐标、字段和项目绑定；
- 分页查询、关系解析、frontier 计算和状态分类；
- 根据已确认上下文起草 Spec 和 Ticket；
- 创建批准后的 Wiki/Base 产物并回查；
- 建立、刷新和校验 Trellis 映射；
- 在 Inline 或 Trellis 中实现代码、运行测试并整理证据；
- 为 Close 生成验收映射、证据表和候选 patch。

`协作模式=AFK` 只代表执行阶段适合交给 Agent，不代表全程无人参与。当前没有 `ready-for-human` 状态；人工参与由 HITL 门禁、`待评审` 和显式确认表达。

## 4.4 运行时边界

1. 不用标题更新记录，始终使用稳定 record ID。
2. 不猜 Base、table、view、Wiki 节点或项目名，全部来自项目契约和真实解析。
3. 不把未知 JSON 响应当成空结果。
4. 不因 `ok: true` 宣称成功，所有写入都要回查。
5. 不把 bot ID 写进 `最后更新人`。
6. 不覆盖 `负责人` 来表达归因。
7. 不跨项目建立父子或依赖关系。
8. 不把 Wiki Spec 全文复制成另一份 Trellis 业务 Spec。
9. 不把 `task.py finish` 当作 Trellis 完成。
10. 不因测试通过、Agent 评审通过或 Trellis 归档自动关闭飞书记录。
11. Ticket 收口和 Spec 最终收口分别获得人工确认。
12. 没有直接验证证据时，记录“未运行”及原因，不能声称完成。

## 4.5 各系统各管一段

```text
对话 / 研究 / 原型
        │ 需求决定、验收和风险
        ▼
飞书 Wiki：Engineering Spec、Map、研究和决策长文
        │ 长文链接
        ▼
飞书 Base：Spec/Ticket 状态、负责人、父子关系、依赖和证据摘要
        │ 执行上下文映射
        ▼
Trellis：计划、多会话上下文、快照和归档
        │ 代码与验证
        ▼
代码仓库：实现、测试、ADR 和真实引用
```

最终闭环是：需求在进入 Base 前已经明确，Wiki 保存可读的正式产物，Base 保存可查询的工作状态，Trellis 保存执行上下文，代码仓库保存实现事实；人工只在关键决策、认领和收口处拍板。