# 演示叙事：源码阅读档案（dsh-codevault）
# —— 一个"读代码的人的第二本笔记本"的 3 分钟故事线

> 本文为参赛演示视频（3–5 分钟）/ 答辩讲解的故事脚本草案。
> 素材来自插件自身的真实使用记录（数据根：`<vault>/源码阅读/`，截至本稿 9 条事件、2 篇深读）。
> 叙事主线：**一个工具，用它自己，讲它如何帮人读懂它所在的生态。**
> 评分对应：问题与场景价值 / AI 与开源融合 / 实现完成度 / 开放成果。

---

## 0. 一句话（作品简介备选，≤300 字内可拆用）

> 读开源代码的人都有一个痛点：读过的机制像听过就忘的唱片。dsh-codevault 是一个装进
> DeepSeek Harness（dsh）的个人"源码阅读档案"插件：在读懂的瞬间用一句自然语言快记，
> 让模型按"坐标式"阅读框架把理解落成 Markdown 对象卡；同一段代码重读多次会累积成一张
> 会生长的卡（阅读时间线 + 去重提炼），并自动关联用户 Obsidian 知识库里的已有笔记。
> 档案本体是纯本地、零网络的 Markdown + JSONL，可被 Obsidian 直接打开做图谱回看。

---

## 1. 开场（约 30s）：从痛点切入，不介绍功能

**画面**：屏幕上是深色编辑器/终端，光标停在一段 dsh 源码注释上。

**旁白（口吻：研究者/开发者自述）**：
> 读开源代码是很多人学东西的方式，但有一个几乎所有人都有的问题：读的时候觉得懂了，
> 一周后问自己"这个机制到底怎么工作的"——答不上来。聊天记录沉底，笔记散落，重读时
> 没有记忆。

**画外提示（字幕）**：
- 不是又一个"AI 帮你读仓库"的总结器；
- 是"帮你记住你读懂了什么"的**读者档案**。

> 我们做的不是让 AI 替我读代码（那类工具已经很多），而是让 AI 做我的**档案管理员**——
> 我读，它记；我重读，它帮我把理解连成历史。

---

## 2. 第一次使用（约 60s）：快记 → 一张卡

**画面**：在 dsh web 对话里，模型正在读 `deepseek-ai/deepseek-harness` 的源码，用户开口。

**对话实录（可还原）**：
> 用户：把刚才读到的记一下：dsh 的 src/index.ts，apply 是插件入口，inject 声明依赖。

**画面切到 Obsidian**：`源码阅读/notes/` 下出现新对象卡，展示：
- 文件名 = 内容标题（人类可读，非随机 id）；
- front-matter 里的结构化坐标（repo/path/symbol）；
- 正文不是一句话，而是"机制/关键点/为什么"。

**旁白**：
> 快记只花十秒，但落下来的不是一行字，而是一张带坐标的卡片——repo、路径、符号、时间、
> 我为什么读它，全都在。

**画外（强调设计取舍）**：
> 卡片文件名由内容标题生成并在首次写入时冻结——这不是小事。Obsidian 的链接靠文件名解析，
> 文件名冻结 = 链接永不漂移，重读、升级都不会产生 `xxx-2` 碎片。

---

## 3. 高潮 1：同对象重读 = 理解生长（约 60s）

**画面**：一周后（演示中用"第二次"代替），用户再次读同一个符号。

**对话实录**：
> 用户：给 cordis 的 service 注入机制写篇深读笔记。
> 用户（第三次）：把刚才那条 apply 的快记展开成深读笔记。

**画面**：Obsidian 打开同一张卡，展示三处变化：
1. 卡片顶部 `readCount` 从 1 → 2 → 3；
2. "阅读时间线（新→旧）"逐段累积，快记与深读混合；
3. "全部提炼要点"跨事件去重合并，**理解随重读生长**。

**旁白（点出与"对象卡"的关系）**：
> 关键不是"记了三条"，而是这三条始终是**同一个对象**。仓库级、文件级、符号级由坐标的最深
> 粒度自动区分——同一个文件读三次是一张卡；文件与文件里的符号是不同卡。碎片消失了。

**画外（工程正确性，给评委）**：
> 底层是"事件流与投影分离"：JSONL 只追加事件（可回放、可测试），Obsidian 卡片、hub、MOC
> 都是每次从事件重建的派生视图——永远不会漂移。

---

## 4. 高潮 2：档案长进你的知识库（约 60s）

**画面**：用户在 Obsidian 的图谱视图里，放大。

**旁白**：
> 档案不该是孤岛。我们读的这段 plan-mode 机制，和用户知识库里那篇 ReAct 笔记其实是同一类问题。

**演示操作**：
1. `vault_suggest`（主题词 ReAct / agent / 推理）→ 候选排序，ReAct 笔记排第一（命中 3 词）；
2. 用户确认"关联第 1 篇"；
3. `read_link` 补链；
4. Obsidian 图谱出现一条**从源码阅读卡指向 ReAct 笔记的边**。

**画面定格图谱**：一端是"plan-mode 的 PlanProjection…"，一端是"ReAct、Plan-and-Solve、Reflection"。

**旁白**：
> 读源码的人要的不是孤立笔记，是把"代码里的机制"和"脑子里已有的概念"连起来。这条边，
> 是这个插件存在的理由。而且全程只读、路径限定在 vault 内——它从不动你的其他笔记。

---

## 5. 狗粮段落（约 30s）：用工具读工具自己

**画面**：切回 dsh 代码，指出本插件的代码仓库就是它自己的档案对象。

**旁白**：
> 最后一件诚实的事：这个插件读过最多的源码，是它自己的宿主与它自己。你现在看到的每一张
> 卡片——对象卡投影、冻结文件名、补链闭环——都是开发它的过程中，它自己记下来的笔记。
> 它不只是被演示，它是被使用着长大的。

**可展示**：`dsh-codevault` 仓库 hub 页，2 个对象的多条记录。

---

## 6. 收束（约 30s）：边界与开放

**旁白**：
> 我们刻意没做的事：不读你的仓库、不生成仓库地图、不替你做总结、不联网、不评分——档案记
> 的是理解，不是评价。它是一个**只写你自己数据库目录的本地工具**，全部数据是 Markdown +
> JSONL，Obsidian 可以直接打开，也可以被任何工具消费。

**开放成果一句话**：
> 插件以 MIT 开源，含《开源及第三方资源使用清单》——所有依赖均为 MIT/Apache-2.0，
> 运行不依赖任何网络与第三方服务。

---

## 附录 A：对应评分项的自检

| 评分项 | 本叙事如何支撑 |
|---|---|
| 问题与场景价值 15 | 开场从"读过的代码像听过就忘"的亲身痛点切入；场景 = 学生/开发者系统学开源项目 |
| 创新性与方案设计 20 | 区分"读者档案 vs 仓库地图"；对象卡、事件-投影分离、冻结文件名、补链闭环均为自主设计 |
| AI 与开源融合 20 | AI 做档案管理员（按阅读框架写作）；开源宿主 dsh + Obsidian 生态 + 阅读对象为开源仓库 |
| 实现完成度 25 | 真实使用记录为证（对象卡/时间线/深读/补链），可当场演示；smoke 104 项自动化断言 |
| 开放成果 15 | MIT 开源插件 + THIRD-PARTY 清单 + vault 目录本身就是可消费开放成果 |

## 附录 B：建议补拍的"真实成长"镜头（可选增强）

- 把 plan-mode 那条快记（唯一带真实 ReAct 关联的卡）升级为深读笔记，让视频里出现
  "快记 → 深读 → 补链 → 图谱边"四连动；
- 花 2–3 天真实使用攒 15–20 条记录再录视频，时间线更有说服力；
- 在视频中使用"9 条真实记录"而非造数据——评委若核验可复现。

## 附录 C：录制合规提醒

- 全程不出现学校名称 / LOGO / 指导教师信息（比赛材料规范）；
- 视频 3–5 分钟、MP4、≤300MB；如引 Obsidian 界面，保留真实 vault 名即可。