内容
# NOAT
**类Notion笔记，存于您的IDE中**。本地优先，git版本控制，可搜索，AI代理可读写，通过MCP。
停止在零散的`.md`文件中或独立应用中记笔记。NOAT在Cursor / VS Code中提供真正的块编辑器，将每个笔记存储在您的机器上，并拥有自己的git历史记录，并为您的AI代理提供一套完整的工具来读取、搜索和编写笔记。
## 功能
### 真正的编辑器，而非文本文件
笔记以正常的编辑器标签页打开，带有Notion风格的块编辑器：输入 `/` 可创建标题、待办事项列表、表格、引用和代码块（语法高亮使用您的编辑器字体）。本地脏状态和撤销功能，以及在您停止输入后自动保存。
### 通过 `@` 链接到代码
在笔记中输入 `@` 以模糊搜索工作区中的每个文件并插入链接芯片。点击芯片，文件将在笔记旁的栏目中打开。路径存储为仓库相对路径，因此链接在不同机器上仍然有效。
### 仓库范围或全局
笔记要么是 **全局**（在任何地方都可见），要么 **限定于某个仓库**（按其 `origin` 远程仓库键控，因此其他机器上的克隆仓库可以看到相同的笔记）。使用文件夹自由组织；可以从侧边栏将笔记移动到不同的范围。
### 类似个人谷歌的搜索
`Cmd+Shift+S` 打开搜索面板，结合两种引擎：
- **关键词** — 模糊的、前缀匹配的、BM25排名的全文本搜索（即时）
- **语义** — 本地嵌入式模型（`all-MiniLM-L6-v2`，约25 MB一次性下载）通过 *含义* 查找笔记：“停止向客户收费两次”会找到您的双重收费事件总结
结果通过互惠排名融合。所有操作都在本地运行 — 无需API密钥，数据不会离开您的机器。
### 通过MCP进行代理访问
捆绑的MCP服务器向AI代理公开您的笔记：
| 工具 | 功能 |
| --- | --- |
| `list_notes` | 列出所有笔记，按范围过滤 |
| `read_note` | 读取笔记为markdown（可选原始块） |
| `get_note_outline` | 大笔记的廉价预览 |
| `search_notes` | 关键词 / 语义 / 混合搜索 |
| `create_note` | 从markdown创建笔记 |
| `append_to_note` | 在现有笔记中追加markdown |
| `replace_note_content` | 重写笔记内容 |
| `get_current_repo_scope` | 将工作目录映射到其笔记范围 |
代理写入纯markdown；NOAT将其转换为真正的编辑器块。在Cursor中，服务器会自动注册 — 无需配置。
### git版本控制，与您的提交同步
`~/.noat` 是其自己的git仓库。笔记编辑立即保存到磁盘，每当您在任何工作区仓库提交时，NOAT会将您的待处理笔记更改快照并附上消息，链接两个历史记录：
```
sync(my-repo): 3942d13 Fix webhook ordering [2026-07-07 16:35]
```
在您的仓库中没有安装钩子 — NOAT通过编辑器的git集成监视提交。
## 安装
从源代码（即将发布到应用商店）：
```bash
git clone https://github.com/pintchom/noat && cd noat
npm install
npm run install-local # 构建、打包并安装到Cursor
```
重新加载编辑器窗口。您将在活动栏中找到NOAT书图标。
> **注意：** 打包的扩展目前为构建平台捆绑原生二进制文件（例如Apple Silicon）。每个平台的应用商店构建正在规划中。
## 快速入门
1. 点击活动栏中的NOAT图标 → **新建笔记**（限定于您的仓库或全局）。
2. 编写。输入 `/` 可创建块，输入 `@` 可链接文件。它会自动保存。
3. 按 `Cmd+Shift+S` 搜索所有内容。
4. 像平时一样提交代码 — 您的笔记会与代码一起快照。
5. 向您的代理询问诸如 *"在我的笔记中搜索ledger迁移计划"* 或 *"将我们刚刚学到的内容保存到这个仓库范围的笔记中"* 之类的问题。
## 快捷键和命令
| 快捷键 | 操作 |
| --- | --- |
| `Cmd+Shift+S` (`Ctrl+Shift+S`) | 搜索笔记（混合） |
| `Cmd+Alt+P` (`Ctrl+Alt+P`) | 搜索笔记（备用绑定） |
| 焦点在NOAT侧边栏时按 `Cmd+P` | 搜索笔记 |
命令面板：`NOAT: 新建笔记`、`NOAT: 新建文件夹`、`NOAT: 搜索笔记`、`NOAT: 重建搜索索引`、`NOAT: 在终端中打开笔记存储`、`NOAT: 刷新笔记`.
## 在Cursor以外设置MCP
Cursor会自动注册MCP服务器。对于其他MCP客户端，请指向捆绑服务器：
```json
{
"mcpServers": {
"noat": {
"command": "node",
"args": ["/path/to/extension/dist/mcp-server.js"]
}
}
}
```
服务器独立运行 — 它直接读取 `~/.noat`，无需编辑器运行。设置 `NOAT_HOME` 以使用不同的存储位置。
## 存储
所有内容都存储在 `~/.noat` 中（可通过 `NOAT_HOME` 覆盖）：
```
~/.noat/
.git/ # 笔记的git历史记录
.cache/ # 嵌入式模型缓存（gitignored）
.index/ # 搜索索引 — 可派生，可重建（gitignored）
notes/
global/ # 全局笔记，允许嵌套文件夹
repos/<repo-key>/ # 限定于某个仓库的笔记
```
笔记是 `.noat.json` 文件：一个小的信封（`id`、`title`、时间戳）围绕 [BlockNote](https://www.blocknotejs.org/) 块数组。普通文件 — 可以 grep、脚本编写、带走。
## 架构
```
┌─────────────────────────────┐
│ Cursor / VS Code │
│ ┌──────────┐ ┌───────────┐ │ ┌──────────────┐
│ │ Webview │ │ 扩展程序 │ │ │ MCP服务器 │◄── 代理
│ │ 编辑器 │◄┤ 主机 │ │ │ （stdio） │
│ └──────────┘ └─────┬─────┘ │ └──────┬───────┘
└─────────────────────┼───────┘ │
▼ ▼
┌─────────────────────────────┐
│ ~/.noat （git仓库） │
└─────────────────────────────┘
```
- **扩展程序主机** — 侧边栏树、命令、git同步、搜索引擎、文件打开操作
- **Webview** — React + BlockNote 自定义编辑器，用于 `*.noat.json`
- **MCP服务器** — 独立的stdio二进制文件，共享相同的核心代码和存储
- **核心** (`src/core/`) — 笔记模型、存储I/O、仓库范围、搜索；无VS Code依赖
## 开发
```bash
npm install
npm run watch # 更改时重建；F5启动开发主机
npm test # 核心单元测试
npm run typecheck # 所有三个目标
npm run lint
npm run seed # 用丰富的演示笔记 + 旧历史记录填充您的存储
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解项目布局和约定。
## 路线图
- 笔记历史查看器（版本已经存在于git中；UI待定）
- 行号文件链接（`file.ts:42`）
- 编辑标题重命名底层文件
- 每个平台的应用商店构建（OpenVSX + VS Code应用商店）
## 许可证
MIT
