Lineage 追溯链路

lineage 是 FylloCode 实现"全程可追溯"的底层机制：一条需求从提出、讨论、形成方案到落地归档，整个过程被记录成一条可回溯的线索。三线工作方式定义了变更可以怎么走，lineage 负责把实际走过的每一步真实地串起来——无论最终走的是直接实现、Plan 还是 Proposal。

核心概念：脉络（Subject）

lineage 中的一条线索称为一条脉络（subject）。一条脉络代表一个需求意图，它包含：

字段	说明
起源（origin）	task 或 chat，记录这条脉络是从任务发起的，还是从对话直接发起的
任务快照（task）	关联任务的引用和快照，包含来源（本地或研发系统）；chat 起源的脉络初始为空
会话链接（links）	这条脉络下的所有 Chat 会话，每个会话记录它产出的 Plan 和 Proposal 列表

一条脉络可以串联多个会话、多个 Plan 和多个 Proposal——同一个任务分多次讨论、产出多个变更，都归属同一条脉络。

链路如何建立

Task ──发起讨论──▶ Chat 会话 ──▶ Plan / Proposal ──▶ Apply & Archive
 │                   │                              │
 └───────────── 同一条 lineage 脉络 ────────────────┘

1. 从任务发起：task 起源

在任务看板从任务卡片发起讨论时，FylloCode 会以该任务为锚点创建（或复用）一条脉络，并把新会话绑定到这条脉络上。对话页顶部会显示来源任务横幅，标明这次讨论属于哪个任务；之后重新进入会话，横幅依然可见。

同一个任务再次发起讨论，新会话会追加到同一条脉络，而不是另起一条。

2. 从对话发起：chat 起源

直接在对话页面开始讨论时，一旦形成最终的方案，FylloCode 会以会话为起点创建一条 chat 起源的脉络。同时展示出一张创建任务的卡片，引导你将方案落地为本地任务。

若对话只是探索，未形成 proposal，它在溯源覆盖指标中暂不计入"已关联任务"。

3. Plan 与 Proposal 自动关联

当会话中的 Agent 通过 fyllo-specs 的 create-plan 或 create-proposal 工具创建 plan 或提案时，对应的 plan slug 或 proposal changeId 会自动记录到会话所在的脉络上。你不需要做任何手动关联——无论这次讨论走的是 Plan 路径还是 Proposal 路径，脉络上都会自然留下记录。直接实现（不调用这两个 tool）则不会产生这类关联，脉络上只保留会话本身。

4. 补建任务：让开放讨论回到主线

chat 起源的脉络可以事后补建任务：

• 在对话中主动可以要求 Agent 创建本地任务，它会通过 fyllo-action 的 task.create 结构化输出提议创建任务，由你确认后执行

补建的任务会回填到同一条脉络上，起源仍标记为 chat，但溯源覆盖会把它计入"已关联任务"。这让"先聊起来再立项"的工作方式也能进入治理主线。

数据存储

lineage 数据完全存储在本地项目数据目录中：

• 每条脉络是一个独立的 JSON 文件（lineage/subjects/<subjectId>.json）
• 一份反查索引（lineage/index.json）维护任务引用、会话 ID、proposal changeId 到脉络的映射，索引可随时从脉络文件重建

不依赖数据库，不上传外部服务，随项目数据一起留在本地。

lineage 在哪里被使用

• 对话页：来源任务横幅，标明会话归属的任务
• 项目概览：溯源覆盖指标、最近脉络列表，以及进行中变更的任务反查，都基于 lineage 投影
• 工作脉络：浏览全部 subject，按状态筛选，并沿 Session 查看 Plan、Proposal 与 Commit
• 归档追溯：变更归档后，从 proposal 反查到会话和任务，回答"这次变更为什么发生、当时讨论了什么"

为什么需要这条链路

git blame 只能告诉你谁提交了代码。lineage 补上的是另外三个问题：

• 这次变更来自哪个任务、要解决什么问题
• 中间经过了哪些讨论、产出了哪个方案
• 方案的取舍和被放弃的方向记录在哪个 proposal 里

这些信息在普通 Agent 会话里会随聊天窗口一起消失；在 FylloCode 中，它们是一条脉络上的结构化数据，几个月后依然可查。