deja-vu 是一个纯本地运行的编码 Agent 记忆工具：它读取 Claude Code、Codex、Cursor 等 40 多个 Agent 已写在磁盘上的会话文件，构建可搜索的记忆索引，并通过 MCP、hooks 和 JSON 接口把"以前查过什么、修过什么"喂回给你的 Agent。如果你在做自己的 Agent 工具链或 harness，想把新的会话格式接入这套记忆索引，这篇文章带你走完全部 6 步。

先搞清楚：你在接入什么

接入前需要理解 deja-vu 的两层结构：

• 解析层（internal/sources/）：每个受支持的 Agent 对应一个解析器，负责把磁盘上的会话文件（JSONL、SQLite、Markdown 等）读成统一的model.Session结构。
• 索引层（internal/index/）：负责文件发现、增量解析和写入索引数据库，它只从注册表读取，新增格式时无需改动。

也就是说，接入新格式的全部工作都在解析层。统一的数据结构定义在 internal/model/model.go，model.Session包含稳定的ID、Harness、Project、Started、Updated和Messages（每条消息含Role、Text、Time），这些字段决定了搜索结果如何分组、排序和归因。

完整的 6 步清单写在 docs/ARCHITECTURE.md 的 "Add a new harness" 一节，下面逐步展开。

第1步：编写解析器，输出 model.Session

在 internal/sources/ 下新增一个<你的harness>.go文件，实现三个函数（命名替换为你的 harness 名）：

func LoadNewHarness() []model.Session // 冷启动全量加载 func ParseNewHarnessFile(path string) ([]model.Session, error) // 解析单个文件 func ParseNewHarnessFileFromOffset(path, offset int64) ([]model.Session, error) // 增量解析（append-only 格式才需要）

要点：

• 会话 ID 必须稳定。索引靠它做增量去重，同一会话跨次构建必须返回相同 ID。
• 消息时间用真实时间戳。deja-vu 的输出大量依赖"最近一次讨论"的时间线，零值时间会被显示为-而不是假日期。
• 增量解析只追加。如果新写入的行可能改写旧记录（比如数据库类格式），就不要实现ParseFrom，让索引整文件重读——正确性优先于速度。
• 参考现有实现：JSONL 类可看 internal/sources/claude.go，SQLite 类可看 internal/sources/codex.go，Markdown 追加日志可看 internal/sources/aider.go。

第2步：在注册表中登记 Harness 条目

打开 internal/sources/registry.go，在allHarnesses()中追加一个Harness条目。核心是两个结构：

• Harness：Name（粗粒度名称，如claude）、Load、Files（返回要索引的文件列表）、Kinds（该 harness 的磁盘文件形态）。
• FileKind：Name、Match（按路径判断归属）、Parse、ParseFrom（可选）、Resumes（可选，声明新增字节能否独立读取）。

⚠️ 最容易踩的坑：Match必须能匹配Files会遍历的每一个根目录。因为增量索引是靠文件路径反查解析器的——路径匹配不上，那个文件的变更就会被静默漏掉。一个 harness 可以有多个FileKind（例如 codex 同时有 rollout 日志和 history 文件两种形态）。

第3步：让增量索引"零改动"自动生效

这是 deja-vu 架构里对贡献者最友好的一点：文件发现、路径匹配、增量解析都在 internal/index/ 中实现，它们统一读取第 2 步的注册表条目，不需要任何编辑。

构建索引时的行为自动继承：

• 文件型来源走按 CPU 核数扩展的 worker 池并行解析，按路径排序后写入，保证确定性；
• 每个 SQLite 类读取有 10 分钟墙钟预算（DEJA_STORE_TIMEOUT可调），超时的 store 会被deja doctor点名，而不是让整个构建卡死；
• 构建是幂等的，索引默认落在~/.cache/deja/index.db。

你唯一要做的验证是：跑一次deja index，确认新会话出现在结果里。

第4步：（可选）接入 install 命令的配置处理

如果 harness 支持 MCP 或 hooks，就让它出现在deja install的可选目标里：在 cmd/deja/install.go 中增加安装/卸载配置处理；接线复杂时（例如需要 hook 而不是单纯 MCP 条目）再建一个install_<harness>.go。

不接这步也可以——解析层先行、安装后补是完全可行的。deja install --help会列出全部 80 多个目标，新目标出现后，deja install --auto的"一条命令全接入"能力会自动覆盖它。

第5步：补上格式注册表文档

deja-vu 把每个受支持格式的磁盘布局当作公开契约维护：

1. 在 docs/registry/registry.json 加一条机器可读条目；
2. 新建docs/registry/<id>.md页面，描述存储位置、文件布局、消息记录结构、角色与时间戳处理、已知怪癖——可参照 docs/registry/claude-code.md 的写法；
3. 在 docs/registry/README.md 的表格里挂上链接。

这一步有强制校验：internal/sources/registry_test.go 会检查注册表索引与allHarnesses()列表双向一致，漏写文档或漏登记都会让测试直接失败。

第6步：加 fixture 和四类测试

测试要覆盖四个面：解析（fixture →model.Session字段断言）、索引（写入后可被检索）、搜索（deja search命中）、install（目标出现在列表）。

两个现成的效率工具：

• 现成 fixture 格式：fixtures/registry/ 下有全部 40 多个格式的合规模板，如 fixtures/registry/claude-code/session.jsonl。如果你的新格式与某个现有格式同族，直接拿一个改造，比手写省事且更贴近真实字节。
• 环境变量隔离：测试绝不能读开发者自己的会话历史。deja-vu 用环境变量（而不是命令行 flag，因为 hooks 和 MCP 是被别人拉起的进程）实现隔离，最小组合：

export DEJA_INDEX_DIR="$tmp/index.db" # 独立索引 export DEJA_STORES=claude # 只启用被测 store export DEJA_CLAUDE_ROOT="$tmp/claude" # 指向你的 fixture

DEJA_STORES接受逗号分隔的 store 列表（deja sources打印的名字）；拼错名字会在命令执行前直接报错——因为一个 typo 若被静默忽略，会让你把"机器没历史"误当成正常结果。internal/testenv/ 包更进一步：它拦截所有DEJA_*位置类变量，防止测试二进制误触开发者真实数据，你的新测试建议直接复用。

最后跑一遍deja doctor --json，确认新 store 在stores[]中出现且路径解析正常。

接入完成后 🎉

至此，你的 Agent 格式就和其他 40 多个一样被搜索、blame、fix、recap等全部命令覆盖。按 docs/INTEGRATING.md 末尾的约定，接入方最好在 issue 或 PR 中说明"我把 deja 接进了 X"——deja-vu 希望这类集成出现在首页而不是藏在 commit 里。

记住三条纪律：ID 稳定、Match 全覆盖、文档与列表双向一致——做到这三点，测试套件会替你走完剩下的路。