# om — 插件化知识库（基于 Foam 二次开发）

<p align="center">
  <a href="https://github.com/xuanlinAI/overmind-slim/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D22.5-blue.svg">
  <img alt="Dependencies" src="https://img.shields.io/badge/dependencies-0-brightgreen.svg">
  <a href="https://github.com/xuanlinAI/overmind-slim"><img alt="Stars" src="https://img.shields.io/github/stars/xuanlinAI/overmind-slim?style=social"></a>
</p>

把超脑 v4 的 66 模块砍到只剩知识库核心，以 **Foam** 为底子重写，按 **DeepSeek Harness 的方式插件化**：

- **Obsidian 兼容** — 你的 vault 就是知识库：纯 markdown 文件 + `[[双链]]` + `#标签` + frontmatter
- **零依赖** — 只用 Node 内置 `node:sqlite`（FTS5 全文检索，内置中文分词）
- **插件化** — 核心暴露稳定接口，用户自己写插件扩展（命令 / MCP 工具 / 事件 / 索引提取器）
- **AI 可接入** — MCP stdio 服务器，Claude Code / Cursor 直接调用

> 致敬 [Foam](https://github.com/foambubble/foam)（MIT）：双链解析语义与图谱模型深受其启发。本项目为独立重写（零依赖，无任何运行时依赖），不是代码 fork。

## 快速开始

```bash
cd ~/om
./core/cli.js init demo          # 初始化（demo 已有示例笔记）
./core/cli.js scan --vault demo  # 建索引
./core/cli.js search 图谱 --vault demo
./core/cli.js rename 图谱 知识图谱 --vault demo   # 重命名，全库双链自动更新
./core/cli.js deadlinks --vault demo             # 死链检查
./core/cli.js orphans --vault demo               # 孤岛笔记
./core/cli.js daily --vault demo                 # 今日笔记
./core/cli.js graph 插件系统 --vault demo
./core/cli.js backlinks 记忆系统 --vault demo
./core/cli.js tags --vault demo
```

日常使用：`cd <你的库> && om search xxx`（`npm link` 后可全局用 `om` 命令）。

## MCP 接入（Claude Code）

```json
// ~/.claude.json 的 mcpServers
{
  "om": {
    "command": "node",
    "args": ["/data/data/com.termux/files/home/om/core/cli.js", "mcp", "--vault", "/path/to/vault"]
  }
}
```

内置工具：`search_notes` / `read_note` / `create_note` / `update_note` / `rename_note` / `delete_note` / `backlinks` / `graph_bfs` / `list_notes` / `list_tags`，加上插件注册的工具。

## 架构

```
vault/                        你的 Obsidian 库（文件即真身）
  .om/config.json             配置（插件开关等）
  .om/index.db                SQLite 索引（可随时删除重建）
  .om/plugins/                你的插件放这里
om/
  core/
    vault.js                  解析 frontmatter / [[双链]] / ![[嵌入]] / #标签
    tokenize.js               中文分词（CJK 单字+双字）+ FTS 查询构造
    db.js / indexer.js        SQLite 索引 + 增量扫描
    graph.js                  图谱查询（邻居 / backlinks / BFS）
    context.js                插件上下文（全部暴露接口）
    plugins.js                插件加载器（dsh 式）
    cli.js / mcp.js           CLI 与 MCP stdio 服务器
  plugins/                    内置示例插件（recent / todos）
```

## 插件编写指南（暴露接口）

插件 = 一个 JS 文件（ESM），默认导出 `{ name, version, description, activate(ctx) }`。
放到 `<vault>/.om/plugins/my-plugin.js`，重启任意 om 命令即生效。`config.json` 里 `"plugins": {"my-plugin": false}` 可禁用。

两条快捷命令：

```bash
om plugin create my-plugin    # 生成插件模板
om plugin install https://github.com/xxx/om-plugin-repo   # 从 git 仓库安装（仓库根目录需含 index.js）
```

`activate(ctx)` 拿到全部能力：

| 接口 | 说明 |
|---|---|
| `ctx.notes` | `get(name)` / `search(q,{limit})` / `create(name,{folder,content,tags})` / `update(name,content)` / `remove(name)` / `list({tag})` |
| `ctx.graph` | `resolve(name)` / `neighbors(ref)` / `backlinks(ref)` / `bfs(ref,depth)` |
| `ctx.tags` | `list()` / `notes(tag)` |
| `ctx.storage` | `get/set/del(key)` — 插件私有 KV（按插件名隔离） |
| `ctx.events` | `on('note:save'\|'note:delete', fn)` — 跨上下文共享的事件总线 |
| `ctx.commands` | `register('名字', async (args) => 输出)` — 新增 CLI 子命令 |
| `ctx.tools` | `register({name,description,inputSchema}, handler)` — 新增 MCP 工具 |
| `ctx.index` | `register(({id,name,frontmatter,body,text}) => ({tags?,links?}))` — 索引提取器，自定义从笔记提取知识 |
| `ctx.health` | `deadlinks()` 未解析链接 / `orphans()` 孤岛笔记 |
| `ctx.db` | 原生 SQLite 句柄（进阶） |
| `ctx.vaultRoot` / `ctx.plugin` | 库路径 / 插件名 |

### 最小插件示例

```js
// <vault>/.om/plugins/hello.js
export default {
  name: 'hello',
  activate(ctx) {
    ctx.commands.register('hello', async () => `你好，库里有 ${ctx.db.prepare('SELECT COUNT(*) c FROM notes').get().c} 篇笔记`);
  },
};
```

```bash
$ om hello --vault demo
你好，库里有 5 篇笔记
```

完整示例见 `plugins/recent.js`（命令+工具+存储+事件）与 `plugins/todos.js`（frontmatter/标签查询）。

## 测试

```bash
cd ~/om && node --test
```

覆盖：分词 / vault 解析 / 索引与增量 / 图谱 / 插件全接口 / MCP 协议端到端。

## 与超脑 v4 的差异

| | 超脑 v4 | om |
|---|---|---|
| 模块数 | 66 | 核心 10 文件 + 插件 |
| 架构 | 6 通道认知神经系统 | 纯知识库 + dsh 式插件 |
| 存储 | 自建多套 | Obsidian 兼容 markdown（文件即真身） |
| 依赖 | npm + pip + 守护进程 | 零依赖（node:sqlite） |
| 扩展 | 不可编程 | 暴露接口，用户写插件 |

## 已知限制（诚实声明）

- 检索为**字面匹配**（FTS5 + 中文单双字分词），非语义检索；同义词/概念检索需靠插件或外部向量服务扩展
- `update_note` 传入正文时**自动保留原 frontmatter**；如需整篇覆写，请连同 `---` 头一起传
- 重命名（`rename` / `rename_note`）会自动更新全库指向它的双链，但**不会**改其他文件里的文本提及
- 单机单进程设计，无分布式/多设备同步（vault 本身是纯文件，可自行用 git 同步）
- 索引为文件系统快照，外部编辑器改动后需 `om scan`（或 `om watch`）刷新