feat: add Feishu user authorization flow documentation and update frontend guidelines

- 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.
2026-08-31 09:18:03 +08:00
parent 3d838866cd
commit dcd6d44960
15 changed files with 3817 additions and 732 deletions
@@ -0,0 +1,689 @@
+# 基于飞书的产物管理工作流
+
+这套流程把需求澄清、规格、拆票、代码实现和收口串到飞书 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 保存执行上下文，代码仓库保存实现事实；人工只在关键决策、认领和收口处拍板。