alluvium: Instructions file for Claude Code

Alluvium · 项目宪法

你（AI）每次进入这个仓库，先读这份文件，再读 docs/LLM_WIKI_DOCTRINE.md。 后者是产品圣经（Karpathy LLM Wiki 模式的忠实落地原则），是判断"实现是否对路"的最终标尺。 任何与本文件或圣经冲突的实现都是错的——遇到分歧请向用户提问，不要自行决定推翻这里的约定。

一句话

Alluvium 是一个 Claude Code session 自动归档器：每次 Claude Code 会话结束后，被动地把对话蒸馏成"精华笔记"，按 Karpathy 的 LLM Wiki 模式合并进用户的 Obsidian vault。

卖点（README slogan）

You don't save your sessions. Your sessions save themselves.

跟同赛道 8 个 obsidian 类项目（claudesidian / claudian / claude-obsidian / obsidian-second-brain 等）的核心差异：

• 别人是主动唤起（slash command / 侧边栏 / MCP 按需调用）；Alluvium 是被动归档（hook 触发，用户无感）。
• 别人多数存原始对话或简单摘要；Alluvium 蒸馏后合并到 topic 页，不留 session 日志。
• 别人多数是 Obsidian 插件或 Claude 内嵌助手；Alluvium 是外部 Rust 二进制 + Claude Code Plugin。

如果 AI 在写"侧边栏"、"slash command"、"per-session note 文件"这类东西，停下来重读本文——多半跑偏了。

知识组织模型（核心，详见 docs/KNOWLEDGE_MODEL.md）

vault 内三层：

<vault>/Alluvium/
├── raw/sessions/        # 不可变原档：每次 session 一份 transcript 副本
├── wiki/
│   ├── index.md         # 主题分类 hub
│   ├── log.md           # append-only 时间线（一行一 session）
│   ├── overview.md
│   ├── concepts/        # 概念、模式、技术（topic 页）
│   ├── entities/        # 项目、工具、人、库（topic 页）
│   └── sources/         # 单 session 摘要（可选层）
└── CLAUDE.md            # vault 内的 schema 文件（注意：这个 CLAUDE.md ≠ 仓库根的这份）

核心原则：知识沉淀到 topic 页（concepts/ 和 entities/），session 不直接变成笔记。session 的最终去处是 raw/sessions/ 作为不可变原档，知识被抽出后向上汇总进 wiki。

Hook 架构（4 个，详见 docs/HOOKS.md）

SessionStart  →  写 `<cache>`/sessions/<id>/resolved.json
PreCompact    →  快照当前 transcript 防 compact 后丢
Stop          →  spawn detached 子进程，hook 立即返回（不卡 Claude Code）
SessionEnd    →  清理临时文件

PreCompact 不能省——长 session 中途 compaction 会丢原始细节。 detached spawn 不能省——蒸馏要 5-30 秒，hook 必须 100ms 内返回。

硬约束（不可违反）

1. 用户是纯 VibeCoder，不写也不读代码。任何代码层选项都要翻译成"对用户可见的影响"才呈现。
2. prompt / config / 中间产物必须是外部文件（toml / yaml / md / json），用户能直接编辑、能用 Obsidian 打开看。
3. 测试是用户的眼睛——功能正确性靠 cargo test 通过/失败回答。测试名要表达用户可见的断言（参考 tests/e2e_*.rs 命名）。
4. 单二进制分发——cargo build --release 出来的二进制独立运行，不依赖 Python / Node 等环境。
5. 保留用户手改——用户可能在 Obsidian 里手动改过任何 wiki 页。merge 时只能覆盖 Alluvium 上次写的部分，必须 diff。
6. 自我引用屏蔽——cwd 在 Alluvium 自己开发目录的 session 不归档（避免递归）。