# Auto MOC and AI Tagger
Version 1.0.3 requires **Obsidian 1.13.0 or later**. See [CHANGELOG.md](CHANGELOG.md) for migration notes and validation scope.

## Development

```sh
npm ci
npm run lint
npm test
npm run build
```

The repository includes official Obsidian lint checks, regression tests, and GitHub Actions build artifacts. Release assets must include `main.js`, `manifest.json`, and `styles.css`; keep `manifest.json` at the root of the default branch.

## Data and network use

Tagging sends the active note body to the configured provider. Recommendations can send up to 2,000 characters from each candidate note across the vault to the configured embedding provider. Local Ollama endpoints keep these requests local; hosted endpoints receive the input. Requests begin when you start processing in the AI panel. Model lists are fetched when the relevant settings render.

API keys are stored in local plugin `data.json` and masked in the settings UI. Embedding vectors and note paths are stored in `embeddings-cache.json`. Neither file belongs in Git. This plugin has no telemetry. Missing Ollama models must be installed manually with `ollama pull <model>`.

Request timeout/cancellation stops waiting and prevents late note writes, but Obsidian's underlying HTTP request may continue at the provider. Existing legacy recommendation sections are preserved on migration; remove any duplicate old section manually.

For more pleasant quick-start, please read: 📖 [docs](https://zhangpl666ya.github.io/auto-moc-ai-tagger/)
Automatically maintain folder-level Maps of Content (MOCs) and use a local or cloud LLM to tag notes and recommend similar notes based on vector embeddings.

## Features

- **Auto MOCs** — Generate and update a `MOC.md` for every folder in your whitelist, listing child folders and notes with their tags, last-modified date, and clickable wikilinks.
- **AI Tagging** — Send notes to Ollama, OpenAI, or Anthropic and write generated tags back to YAML frontmatter.
- **Similar Notes** — Embed note contents with a local or hosted embedding model and show the top-N most similar notes in a side panel.
- **Live Updates** — Create, delete, rename, and modify events update MOCs within a configurable debounce window.
- **Bilingual UI** — Switch between 中文 and English from the settings tab. The plugin UI, generated MOCs, and the LLM tag-extraction prompt all follow the chosen language.
- **Privacy First** — Bring-your-own endpoint. Local Ollama keeps everything on your machine; cloud providers are opt-in.

## Installation

### From Obsidian Community Plugins (after approval)

1. Open **Settings → Community plugins**.
2. Make sure Community plugins are enabled.
3. Click **Browse** and search for `Auto MOC and AI Tagger`.
4. Click **Install**, then **Enable**.

### Manual / BRAT

1. Download `main.js`, `manifest.json`, and `styles.css` from the latest release.
2. Create the folder `<vault>/.obsidian/plugins/auto-moc-ai-tagger/`.
3. Drop the three files inside.
4. Enable the plugin in **Settings → Community plugins**.

## Quick Start

1. Open **Settings → Auto MOC and AI Tagger**.
2. Add the folders you want MOCs for to the **Whitelist** (e.g. `学习`, `工具`).
3. (Optional) Pick a tagging provider. Ollama is the easiest zero-cost option:
   - Install [Ollama](https://ollama.com) and pull a small model: `ollama pull qwen2.5:0.5b`.
   - Set `taggingProvider` to `ollama` (default).
4. (Optional) Pick an embedding provider for similar-notes. Recommended: `nomic-embed-text` via Ollama.
5. Run the command **Update all MOCs** from the command palette (or click the brain-circuit ribbon icon).

## Commands

| Command | What it does |
|---|---|
| `更新所有白名单的 MOC` | Regenerates every MOC in your whitelisted folders. |
| `AI 笔记处理与润色面板` | Opens a modal for the active note: tag it, find similar notes, apply tags. |

## Settings

The plugin stores settings in `.obsidian/plugins/auto-moc-ai-tagger/data.json`. Adjustable from the settings tab:

- **Whitelist** — folders to maintain MOCs for.
- **Recursive** — include sub-folders when generating MOCs.
- **Unclassified Header** — section heading for notes without tags.
- **Clean Broken Links** — strip wikilinks that no longer resolve.
- **Preserve User Content** — keep your handwritten content outside the auto-generated block.
- **MOC Show Stats** — render the top summary callout (folder / note / tag counts).
- **MOC Show Dates** — append a 📅 `YYYY-MM-DD` modification date to each entry.
- **MOC Show Icons** — toggle the emoji chrome (📚 / 📁 / 📄 / 🕒 / 🤖).
- **MOC Tag Style** — render tags as `` `tag` `` (code) or `#tag` (hash).
- **MOC Sort By** — order notes inside each section by `mtime` (default) or `name`.
- **Tagging Provider** — `ollama` / `openai` / `anthropic`.
- **Tag Count / Max Length** — limits on generated tags.
- **Embedding Provider** — `ollama` / `openai` (for similar notes).
- **Max Recommendations** — top-N similar notes to show.

## MOC Layout (v1.1)

Generated MOCs now ship with a stats callout, folder callouts, code-style tags, per-note dates, and a generation footer:

```markdown
---
tags:
  - "笔记/MOC"
moc: true
创建: 2026-06-15
更新: 2026-06-15 14:30
---

# 📚 学习 · 知识地图

> [!info] **📊 知识地图概览**
> 📂 **5** 个子文件夹 · 📄 **42** 篇笔记 · 🏷️ 平均 **3.0** 个标签/篇
> 🕒 最后更新：2026-06-15 14:30

---

## 📁 子文件夹1 · 15 篇

> [!note] 🗂️ 拥有独立 MOC · [[子文件夹1/MOC|查看子目录]]

- 📄 [[Note1|Note1]] `tag1` `tag2` `tag3` · 📅 2026-06-15
- 📄 [[Note2|Note2]] `tag1` · 📅 2026-06-14

## ❓ 未分类 · 5 篇

- 📄 [[Note4|Note4]] · 📅 2026-06-12

---

🤖 Auto-generated by Auto MOC & AI Tagger · 2026-06-15 14:30
```

Existing MOCs are regenerated automatically on the next file event in the folder (or run **更新所有白名单的 MOC** from the command palette to force-refresh the whole tree).

## Privacy

Your notes and embeddings never leave your machine unless you explicitly configure a cloud provider (OpenAI, Anthropic). Embeddings are cached locally in `embeddings-cache.json` inside the plugin folder.

## License

MIT — see [LICENSE](LICENSE).

## Author

zhangpl666ya — https://github.com/zhangpl666ya