内容
# BuildVault
**适用于 [Claude Code](https://claude.com/claude-code) 的持久内存和跨会话感知系统。**
Claude Code 会话是短暂的 — 关闭窗口后，上下文就会丢失。打开两个窗口，它们之间没有任何联系。BuildVault 使用纯 Markdown 文件和几个小型 Node.js 钩子解决了这两个问题。
它执行三个功能，并故意保持独立：
1. **上下文恢复** — 如果会话丢失，每个项目都有一个 *中心笔记*，保存当前状态，因此上下文从磁盘而不是内存中恢复。
2. **构建日志** — 一个诚实、有日期、仅追加的日志（开发日志 + 崩溃日志）— 用于公开构建内容的原始素材。
3. **跨会话感知** — 一个共享的“白板”，允许多个并发会话相互查看对方正在执行的操作并留下笔记。
无需数据库，无需云端，无需安装应用。只需 Markdown + 钩子（以及一个可选的零依赖 MCP 服务器）。
---
## 核心规则：流 vs. 维基
这里存在两种写作方式，具有 **相反** 的规则。不要混淆它们。
| | 流（`devlog`，`crashouts`） | 维基（`decisions`，`Wiki/`） |
| --- | --- | --- |
| 何时编写 | 即时 | 当理解成熟时 |
| 稍后编辑？ | **否 — 仅追加** | 是 — 保持最新 |
| 语气 | 原始，粗糙，诚实 | 清晰，提炼 |
| 为什么 | 原始挣扎是内容黄金 | 这是你将发布或移交的内容 |
流 *供给* 维基：今天你可能会遇到挫折，明天将经验提炼到 `decisions.md`。两者都为你的内容提供支持。
---
## 布局
```
BuildVault/
Home.md 所有项目及其状态的索引
Projects/<name>/
_<name>.md 中心：当前状态（“我在哪里”）
decisions.md ADR 日志（常青）
devlog.md 有日期的旅程（流，仅追加）
crashouts.md 失败，原始（流，仅追加）
Wiki/ 跨项目常青知识
Content/ 从流中挖掘的帖子想法和草稿
_templates/ 复制这些以启动项目
_scripts/ 自动捕获钩子
_sessions/ 跨会话白板 + 钩子 + MCP 服务器
```
---
## 三个自动化部分
### 1. 自动捕获（`_scripts/devlog-autocapture.js`）
一个 `SessionEnd` 钩子。当会话在跟踪的项目中结束时，它会在该项目的 `devlog.md` 中追加一个带有日期的面包屑 — 包括回合数、打开请求、最后一个请求。零努力；永远不会覆盖过去的条目。
### 2. 跨会话感知（`_sessions/`）
一个共享的白板（`board.json`），每个会话都会读取和写入：
- **`hook-register.js`** （SessionStart）— 注册会话 *和* 将其他活动会话注入新会话的上下文，以便它知道其他会话正在运行。
- **`hook-heartbeat.js`** （Stop）— 更新“最后看到”和记录当前任务每个回合。
- **`hook-end.js`** （SessionEnd）— 标记会话结束。
- **`mcp-server.js`** — 一个可选的无依赖 MCP 服务器，暴露相同的白板作为按需工具（`sessions_active`，`messages_list`，`message_post`，`message_resolve`）。
会话仅在最近 30 分钟内看到时才是“活动”的，因此崩溃的会话会过期，而不是永远困扰白板。
### 3. devlog → 帖子（`skills/devlog-to-post/`）
一个 Claude Code 技能，读取 devlog + crashouts 的日期范围，并草拟一个帖子/博客到 `Content/drafts/` — 在流上只读。
> **设计注意：** Claude Code 会话是基于回合的，而不是始终在线的。当会话 *启动* 或 *执行* 时，会发生感知 — 它不能实时中断另一个会话的思考过程。这涵盖了绝大多数“不要冲突/建议帮助”的情况。
---
## 安装
参见 **[docs/INSTALL.md](docs/INSTALL.md)** — 复制文件夹，将三个钩子连接到 `settings.json`，并且（可选）用一个命令注册 MCP 服务器。
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
