提案：以独立会话记录和可重建索引实现无冲突的工作区记忆

[wesleywu]

提案摘要

本提案建议 Trellis 使用相互独立的逐会话权威记录，以及可重新生成的工作区索引。

它的目的不只是规避 #415 中尚未解决的 index.md 冲突，而是在完整保留并增强 Trellis 工作区记忆能力的同时，消除并行任务和工作树之间因共享受跟踪文件写入而产生的合并冲突。

我们已经在 #415 的这条评论 中给出了详细分析和实施经验。本讨论将其整理为一个独立的架构提案，方便维护者和使用者脱离即时缺陷，单独评估这一长期方向。

建议建立以下核心不变量：

相互独立的会话和任务分别产生自己的权威记忆记录；跨会话索引是根据这些记录重新生成的投影视图，而不是每个分支都必须重写的受跟踪权威文件。

如果维护者认可这一方向，我们愿意协助把已经在 Guru Team 中验证过的实现适配回 Trellis 上游，并提交相应的 PR。

工作区记忆真正要实现的目标

根据 Trellis 当前的工作区文档和 finish-work 流程：

• journal-N.md 记录每次会话的进展、决策、变更、测试和后续步骤；
• workspace/<developer>/index.md 汇总近期会话和日志位置，帮助后续智能体快速恢复上下文；
• .trellis/tasks/** 保存需求、设计、实现状态和任务级证据；
• .trellis/spec/** 保存应长期指导后续工作的工程知识。

因此，工作区记忆的根本目标是：

1. 智能体会话结束后，重要上下文不会丢失；
2. 后续智能体不必读取全部日志，也能快速找到相关历史；
3. 会话过程、任务事实和长期项目规则具有清晰且不同的生命周期；
4. 历史记录能够关联分支、提交、测试结果和后续动作；
5. 多个开发者、窗口、任务和工作树产生的记录能够同时存在，并完整保留彼此的结果。

journal-N.md 和 index.md 是实现这些目标的机制，而不是目标本身。

当前存储模型为什么会与并行工作树冲突

当前工作区记忆按开发者划分写入路径：

.trellis/workspace/<developer>/journal-N.md
.trellis/workspace/<developer>/index.md

当同一名开发者同时使用多个工作树时，多个相互独立的工作流执行单元会：

• 向同一个日志文件追加会话；
• 分别读取旧状态后，重新计算并覆盖同一个索引；
• 在各自分支中提交这些结果。

这使开发者身份同时承担了两个彼此无关的职责：

• 表达“是谁在工作”；
• 定义“不同执行单元应写入哪些 Git 路径”。

在单窗口工作流中，这两个职责看起来一致；在同一开发者并行处理多个任务时，它们并不一致。

v0.6.9 引入的 merge=union 是针对只追加日志的有效短期修复，但它无法正确合并两个分别基于同一旧状态重新生成的索引。选择任意一边虽然不会破坏 task.json 中的任务权威状态，却仍然会：

• 丢失另一个分支产生的导航投影；
• 使索引暂时不完整或过期；
• 中断自动化合并流程；
• 要求使用者手工解决一个已经被定义为派生数据的文件。

为每个工作树创建不同的 Trellis 开发者身份，可以绕开一部分路径冲突，但会拆散同一个人的历史，并迫使人员身份适应存储布局，因此不适合作为长期正确性边界。

建议的信息模型

将权威记忆事实与面向智能体和人类的投影视图分离：

相互独立的权威记录
          ↓
      查询与投影
          ↓
智能体和人类可阅读的上下文

一、相互独立的会话记录

每次会话应创建一个可以稳定寻址的独立记录，而不是追加到所有工作树共享的权威日志文件中：

.trellis/workspace/<developer>/sessions/<session-id>.json

如果更倾向于使用 Markdown，也可以采用：

.trellis/workspace/<developer>/sessions/<session-id>.md

每条记录可以包含：

• 结构版本和稳定的会话标识；
• 开发者及来源平台、来源会话引用；
• 创建和完成时间；
• 标题、摘要、主要变更、测试和后续步骤；
• 分支和提交；
• 可选的任务引用；
• 完成状态。

与任务相关的会话可以关联 .trellis/tasks/**；没有正式任务的普通会话也仍然可以记录，从而完整保留 Trellis 当前的通用会话记忆能力。

文件名不应依赖一个需要跨工作树共同递增的全局会话序号。展示顺序和面向人类的序号可以根据时间和稳定标识派生。

二、可重新生成的索引

开发者级索引和全局工作区索引可以改为以下任一形式：

• 查询时实时输出；
• 写入被 Git 忽略、可以随时重建的缓存；
• 通过显式渲染命令生成的人类可读视图。

它们仍然可以展示：

• 最近会话；
• 当前工作；
• 会话和日志位置；
• 会话总数；
• 任务、分支和提交导航。

区别只在于，索引不再承担权威记忆职责，也不再要求每个功能分支都提交对它的修改。

如果使用者希望继续直接阅读现有的 journal-N.md，日志可以保留为根据独立会话记录聚合生成的兼容视图，而不再是唯一的权威存储。

为什么该模型能够彻底消除这一类合并冲突

使用独立记录后，同一开发者的两个工作树会写入不同路径：

工作树 A -> sessions/<session-a>.json
工作树 B -> sessions/<session-b>.json

合并操作由“合并两个竞争性的整文件重写结果”，变成“合并两个不同的文件集合”。

无论采用哪一种合并顺序：

• 两条权威记录都会存在；
• 不需要选择或丢弃任何一边；
• 索引根据合并后的全部记录重新生成；
• 生成的投影视图同时包含两个会话；
• 不需要自定义合并驱动，也不需要人工解决冲突。

这一方案解决的是写入归属的根本问题，而不是在未来每出现一个新的共享文件时，再为该文件增加一条特殊合并规则。

如何增强原始工作区记忆目标

该模型不是以削弱记忆能力换取合并安全，而是进一步增强原始目标：

• 并行产生的多个结果都会作为独立事实被完整保留；
• 索引的完整性不再依赖分支合并顺序；
• 检索维度可以从开发者和时间扩展到任务、分支、提交、路径、问题、结果、合同和代码符号；
• 摘要记录可以直接链接到详细任务材料和验证证据；
• 开发者身份继续表达人员身份，但不再承担并发写入隔离职责；
• 会话事实、任务事实、项目规范和本机运行状态具有更明确的权威边界；
• 仓库迁移、克隆或部分历史更新后，派生索引都可以根据权威记录重新生成。

Guru Team 中已经实施的方案

Guru Team 是以任务为中心的工作流，因此其具体实现采用任务本地的完成记录：

.trellis/tasks/archive/<YYYY-MM>/<task-slug>/finish-summary.json

每份摘要包含：

• 问题和结果；
• 行为变化和受影响范围；
• 合同变化；
• Issue、PR、分支、提交和变更路径；
• 可检索的命令、配置项、结构字段、代码符号和短语；
• 指向需求、设计、实现、审核和测试证据的任务相对路径。

历史发现不会维护一个受跟踪的全局索引。它会扫描已归档任务的 finish-summary.json，返回少量候选，再由智能体按需读取选中的任务材料、Issue、PR、Git 差异或原始会话记录。

最终形成以下知识分层：

活动和归档任务材料       -> 具体变更事实
finish-summary           -> 分布式历史检索单元
平台原生会话日志和 mem   -> 原始对话历史
spec                     -> 长期工程规则
被忽略的 runtime         -> 本机临时状态

既有归档任务通过保守的一次性回填获得自己的 finish-summary.json。无法恢复的信息会被明确报告，而不是凭空推断；整个迁移不会创建新的受跟踪全局索引。

将该模型移植回 Trellis 上游的大致工作

Guru Team 的改动包含扩展特有的工作流、Skill 和任务收尾合同，因此不能直接拣选提交。但底层信息模型可以分阶段适配回 Trellis 上游。

一、定义上游记忆合同

需要先确定：

• 记录结构及其版本；
• 稳定会话标识；
• 记录路径和排序规则；
• 开发者、时间、分支、提交、摘要、测试和后续步骤等字段；
• 可选的任务关联；
• 没有任务的普通会话如何记录；
• 哪些字段是权威事实，哪些字段只是派生展示。

该合同应保持平台中立，并且不依赖 Guru Team 工作流。

二、增加独立会话记录写入器

重构 add_session.py，使其：

• 每次调用只创建一条可以独立寻址的记录；
• 不再把共享递增计数器作为会话身份；
• 不再追加所有工作树共享的权威日志；
• 不再重写受 Git 跟踪的索引；
• 自动提交时只暂存新的会话记录和明确属于当前任务的路径；
• 同一开发者的两个工作树可以产生没有路径交集的 Git 元数据差异。

迁移期间可以继续生成兼容的日志和索引视图，但新的独立记录应成为权威来源。

三、增加统一的读取器和投影器

提供统一读取能力，用于：

• 扫描逐会话记录；
• 将会话记录与任务状态关联；
• 生成开发者级和全局工作区概览；
• 为 get_context.py 输出精简上下文；
• 按时间、任务、分支、提交和关键词检索；
• 按需生成兼容的 index.md 和 journal-N.md 阅读视图。

投影过程应当只读，或者只写入被 Git 忽略、可以重新生成的缓存。

四、调整工作流消费者和模板

需要同步检查和修改：

• finish-work 命令和 Skill；
• add_session.py；
• get_context.py 和 session_context.py；
• 工作区初始化；
• 开发者初始化；
• 会话自动提交的路径白名单；
• 工作区文档；
• 各平台生成模板及安装副本。

finish-work 仍然负责记录会话，只是把记录目标改为独立的权威会话记录。

五、提供保守的兼容迁移

对于既有仓库：

• 发现现有 journal-N.md 和 index.md；
• 将能够可靠解析的日志会话区块回填为独立记录；
• 原样保留无法解析或经过用户定制的内容，不静默删除；
• 保证迁移可重复执行；
• 过渡期间同时支持新记录和旧日志读取；
• 确保 trellis update 不覆盖用户定制的工作区内容；
• 迁移后根据权威记录重新生成索引。

可以采用以下渐进发布顺序：

1. 新增记录结构、读取器和投影器，但暂不切换现有写入器；
2. add_session.py 同时写入新旧结构，读取端优先使用新记录；
3. 发布迁移和回填能力；
4. 停止普通流程对共享日志和索引的受跟踪写入；
5. 将旧日志和索引保留为兼容视图或只读历史。

六、增加并行工作树验收

最终验收应验证完整的记忆不变量，而不只是某一条合并属性：

1. 从同一个干净基线创建两个工作树；
2. 使用同一个开发者身份；
3. 两边分别记录不同会话，并允许关联不同任务；
4. 分别完成提交；
5. 验证 A -> B 和 B -> A 两种合并顺序；
6. 两次合并均不得出现工作区元数据冲突；
7. 两条会话记录都必须完整保留；
8. 投影视图必须同时展示两个会话；
9. 会话数量、排序以及任务、分支和提交导航必须正确；
10. 旧数据迁移、全新初始化和 trellis update 都必须通过。

验收矩阵还应包含没有任务的普通会话，确保该方案适用于 Trellis 通用工作流，而不是只服务任务型工作流。

已有实现与验证参考

Guru Team 的实现和验证历史均可公开查看：

• #53：原始问题拆分与最终关闭证据
• PR #102：分离任务事实、本机运行状态和共享配置
• PR #103：以任务本地、可检索的完成记录替代共享工作区日志写入
• PR #104：回填历史检索记录
• PR #107：重构收尾事务，保证最终记录完整
• PR #141：历史发现与 A/B 双向工作树合并验证
• PR #175：最终工作流和写入归属收敛

集成验证会从同一个干净基线启动两个任务，分别完成创建、收尾、归档和提交，然后验证两种合并顺序。两份历史记录都会被保留和发现，两个分支也不会写入共享的受跟踪工作区、索引或缓存路径。该回归与 644 项测试、干净安装、更新后重新应用、平台投影和漂移检查一同通过。

协作建议

如果维护者认可“独立权威会话记录加可重新生成索引”这一总体方向，我们愿意协助把该设计适配到 Trellis 上游并提交 PR。

在开始实现之前，希望得到以下方向的反馈：

1. 上游是否接受逐会话权威记录；
2. 记录应使用 JSON、Markdown，还是结构化元数据加 Markdown 正文；
3. index.md 应改为查询时输出、被 Git 忽略的缓存，还是显式渲染产物；
4. 新旧日志和索引需要同时读取多长时间；
5. 维护者更倾向多个小型迁移 PR，还是先提交一份设计合同 PR 再确定实施拆分。

如果方向获得认可，我们可以先提交一份只包含上游数据合同、迁移计划和验收矩阵的设计 PR。之后再分阶段实现写入器、投影器、迁移能力和工作树集成测试。