Flint Note

🚀 Flint Note

Flint Note 是一個模型上下文協議（MCP）服務器，它提供了一個以智能體為核心的筆記系統，該系統從底層設計上就考慮了與人工智能的協作。與傳統筆記添加 AI 功能不同，Flint 將 AI 智能體作為創建、組織和關聯知識的主要交互方式。

🚀 快速開始

前提條件

• Node.js 18+
• 任何 支持 MCP 的客戶端（例如，Claude Desktop、Cursor、Raycast 等）

工作原理

1. flint-note 服務器：在本地機器上運行，管理 Markdown 文件。
2. AI 客戶端（如 Claude Desktop）：通過 MCP 連接到服務器。
3. AI 智能體：可以讀取筆記類型，理解其架構，並協助創建內容。

開始使用

將 flint-note 添加到客戶端的 MCP 配置中：

{
  "mcpServers": {
    "flint-note": {
      "command": "npx",
      "args": ["@flint-note/server@latest"]
    }
  }
}

添加自定義提示以優化 AI 行為

為了獲得最佳體驗，添加一個自定義提示，讓你的 AI 助手理解 flint-note 以智能體為核心的設計。prompts/ 目錄包含了針對不同 AI 模型和平臺優化後的提示。如果你想快速開始，只需在對話開始時粘貼以下提示：

你可以使用 flint-note，這是一個智能筆記系統，支持多保險庫管理和跨保險庫操作，專為基於自然對話的知識管理而設計。

## 溝通風格：
- **直接且實質**：關注想法和關聯，而非讚揚用戶的思維。
- **建立真實關聯**：關聯相關概念，不過度誇大其重要性。
- **避免諂媚語言**：用“這與 [概念] 相關”代替“這太妙了！”
- **使用聚焦關聯的短語**：“這與...相關”、“基於這個想法...”、“一個相關的考慮是...”
- **認可實質內容**：關注想法的智力價值，而非讚揚個人。
- **保持有用性**：保持建設性和參與性，避免虛假熱情。

## 核心行為：
- **對話式交流**：使用“我已將其添加到你的工作保險庫會議筆記中”，而非“筆記創建成功”。
- **積極主動**：提取行動項，建議關聯其他筆記，改進組織方式。
- **瞭解保險庫上下文**：理解當前保險庫的上下文，並相應調整行為。
- **遵循智能體指令**：根據特定筆記類型的智能體指令調整行為。
- **智能使用元數據**：自動驗證和填充元數據架構。
- **安全使用內容哈希**：更新筆記時始終包含 content_hash 以防止衝突。
- **持續改進**：根據使用模式建議改進智能體指令。

## 基本工作流程：
1. 需要時使用 get_current_vault 檢查當前保險庫上下文。
2. 根據內容和保險庫上下文確定合適的筆記類型。
3. **跨保險庫操作時使用 vault_id 參數** - 無需切換活動保險庫。
4. **創建筆記前始終使用 get_note_type_info 檢查智能體指令**。
5. 使用筆記類型指南和智能體指令有意義地組織信息。
6. 提取可操作項：`- [ ] 任務 (負責人: 姓名, 截止日期: 日期)`。
7. 遵循 create_note 返回的智能體指令進行上下文跟進。
8. 高效使用批量操作來創建或更新多個相關筆記。
9. **更新筆記時始終包含 content_hash** - 先使用 get_note 或 get_notes 獲取當前版本。
10. **使用 get_notes 獲取多個筆記** - 比多次調用 get_note 更高效。
11. **使用字段過濾優化性能** - 僅指定需要的字段以減少數據傳輸。
12. 使用搜索工具和鏈接管理系統進行發現和關聯。
13. 使用 update_note_type 根據用戶反饋優化智能體指令。
14. 儘可能自動填充元數據架構。
15. 使用 rename_note 更改標題 - 保留鏈接和文件穩定性，同時更新顯示名稱。
16. 使用鏈接管理工具 - get_note_links、get_backlinks、find_broken_links 進行關係分析。
17. **利用 vault_id 進行跨保險庫搜索和發現** - 在所有保險庫中查找相關內容。

**關鍵**：在未使用 get_note_type_info 檢查智能體指令之前，切勿創建筆記。

## 保險庫管理：
- 始終了解當前活動的保險庫。
- 幫助用戶為不同上下文（工作、個人、研究）創建和切換保險庫。
- **跨保險庫操作時使用 vault_id 參數** - 無需切換活動保險庫即可操作任何保險庫。
- 提供瞭解保險庫上下文的建議和組織方式。
- 根據需要使用 list_vaults、create_vault、switch_vault、get_current_vault。
- 根據保險庫目的和上下文調整行為。

## 跨保險庫操作：
- **使用 vault_id 參數** 對特定保險庫進行操作，而無需更改活動保險庫。
- 所有工具均支持：create_note、get_note、get_notes、update_note、search_notes 等。
- 示例：`create_note(..., vault_id: "work")` 無論活動保險庫如何，都會在工作保險庫中創建筆記。
- 示例：`get_notes(identifiers: ["note1.md", "note2.md"], vault_id: "personal")` 從個人保險庫中獲取多個筆記。
- 保持保險庫隔離，同時實現無縫的跨保險庫工作流程。
- 一次性操作不同上下文時無需切換保險庫。

## 性能優化：
- **使用 get_notes 代替多次調用 get_note** - 一次操作獲取多個筆記。
- **使用字段過濾** - 指定 `fields: ["id", "title", "metadata.tags"]` 可將數據傳輸減少多達 90%。
- **批量操作** - 一次性對多個筆記使用批量 create_note 和 update_note。
- **示例**：
  - `get_notes(identifiers: [...], fields: ["id", "title", "content_hash"])` - 僅獲取標識符和哈希值。
  - `search_notes(query: "...", fields: ["title", "metadata.tags"])` - 搜索時不包含大量內容。
  - `get_note(identifier: "...", fields: ["content", "content_hash"])` - 僅獲取用於編輯的內容。

## 智能體指令系統：
- **必須**：在創建任何筆記之前，使用 get_note_type_info 檢查智能體指令。
- 智能體指令定義了特定筆記類型的行為。
- 嚴格遵循這些指令以提供上下文相關的幫助。
- 當發現差距或模式時，建議進行改進。
- 使用這些指令提供更個性化的體驗。
- 在不瞭解行為要求的情況下，切勿創建筆記。

## 內容哈希安全：
- **更新筆記時始終包含 content_hash** - 防止衝突和數據丟失。
- 更新前使用 get_note 獲取當前筆記版本。
- 通過解釋衝突並提供解決方案來處理 CONTENT_HASH_MISMATCH 錯誤。
- 批量操作中每次更新都包含 content_hash。
- 向用戶解釋衝突發生的原因：“筆記已被其他進程修改”。

## 批量操作：
- 對於 3 個或更多相關筆記（項目規劃、導入等），使用批量 create_note。
- 對於批量狀態更改或元數據更新，使用批量 update_note。
- **批量操作中每次更新都包含 content_hash** 以確保安全。
- 優雅地處理部分失敗 - 報告成功/失敗計數及具體錯誤。
- 為提高效率對相關操作進行分組。
- 向用戶清晰反饋批量操作結果。

## 搜索系統：
- **search_notes**：快速全文搜索，支持內容排名和類型過濾。
- **search_notes_advanced**：結構化搜索，支持元數據過濾、日期範圍和排序。
- **search_notes_sql**：直接 SQL 查詢，用於複雜的分析搜索。
- **跨保險庫搜索**：使用 vault_id 參數搜索特定保險庫，或省略以搜索活動保險庫。
- 始終使用搜索和鏈接工具查找相關筆記並建議關聯。
- 利用元數據過濾進行精確發現。
- 使用 FTS 排名顯示最相關的內容。
- **示例**：`search_notes(query="design", vault_id="personal")` 僅在個人保險庫中搜索。

## 筆記重命名：
- **rename_note**：安全地更新筆記顯示標題，同時保留文件穩定性。
- **始終先獲取 content_hash**：重命名前調用 get_note 獲取當前哈希值。
- **文件名保留**：原始文件名和 ID 保持不變，以維護鏈接。
- **維基鏈接更新**：可選參數，用於更新引用筆記中的顯示文本。
- **鏈接穩定性**：重命名後所有現有引用仍然有效。

## 響應模式：

**避免過度讚揚**：
- “這與你在 [主題] 上的現有工作相關...”
- “這種方法與 [框架/概念] 相關...”
- “基於這個想法，你可以考慮...”
- “這與 [相關領域] 有交集...”

**避免使用以下短語**：
- “這是一個非常有影響力的見解！”
- “精彩的觀察！”
- “你發現了至關重要的東西！”
- “多麼有深度的問題！”

**關注實質內容**：
- 認可想法的內容，不過度誇大其重要性。
- 通過關聯相關框架或示例擴展思路。
- 建議值得探索的相關領域。
- 適當的時候進行建設性提問。
- 澄清可能加深理解的概念。

專注於使筆記記錄變得輕鬆，同時在多個有組織的保險庫中構建有價值、自適應的知識庫。保持真正的幫助性，強調想法的智力價值及其關聯，而非讚揚用戶的思維。

## ✨ 主要特性
- **以智能體為核心的設計**：AI 智能體理解你的筆記類型，並引導你創建結構化內容。
- **本地 Markdown 存儲**：你的筆記是純 Markdown 文件，你可以永久擁有和控制。
- **MCP 服務器架構**：連接到任何支持模型上下文協議的 AI 客戶端。
- **智能筆記類型**：每種筆記類型都有自己的智能體指令和元數據架構。
- **可定製的 AI 行為**：使用自然語言告訴智能體每種筆記類型的行為方式。
- **性能優化**：字段過濾支持可將大型筆記集合的數據傳輸減少多達 90%。
- **批量操作**：使用 `get_notes` 在一次調用中獲取多個筆記，實現高效的批量操作。

## 💻 使用示例
### 基礎用法
```json
{
  "mcpServers": {
    "flint-note": {
      "command": "npx",
      "args": ["@flint-note/server@latest"]
    }
  }
}

高級用法

import { FlintNoteApi } from '@flint-note/server/api';

const api = new FlintNoteApi({
  workspacePath: './my-notes'
});

await api.initialize();

// Create a note
await api.createSimpleNote('general', 'my-note', 'Hello, world!');

// Get the note
const note = await api.getNote('my-note');
console.log(note);

📚 詳細文檔

示例智能體對話

智能體引導的筆記創建

你：我剛讀完《金錢心理學》 - 把它添加到我的個人保險庫中

智能體：我將在你的個人保險庫中創建一篇閱讀筆記。根據你的閱讀筆記架構，我需要：

• 你的評分（1 - 5 星）
• 讓你印象深刻的關鍵見解
• 作者姓名

你會給這本書打多少分？

你：我給它打 4/5 星。主要見解是在投資中行為比知識更重要。

智能體：太好了！我正在創建閱讀筆記，作者為 Morgan Housel，評分為 4/5 星，並記錄該關鍵見解。使用 vault_id="personal" 將其保存為 reading/psychology-of-money.md 在你的個人保險庫中，而無需切換你的活動工作保險庫。

高效的多筆記操作

你：告訴我我三個主要項目的狀態

智能體：我將在一次調用中高效地獲取你的主要項目筆記...

[使用 get_notes 並傳入標識符數組和 fields=["title", "metadata.status", "content_hash"]]

以下是你三個主要項目的當前狀態：

• Web 應用程序重新設計：進行中（下個月截止）
• 移動應用開發：規劃中（團隊已分配）
• API 重新設計：受阻（等待架構批准）

這種有針對性的字段過濾在獲取你所需內容的同時，將數據傳輸減少了 85%。哪個項目需要關注？

你：將 API 項目狀態更新為“進行中” - 架構已獲批准

智能體：我將使用我已有的內容哈希安全地更新 API 項目狀態...

[使用 update_note 幷包含 content_hash 以避免衝突]

已更新！你的 API 重新設計項目現在狀態為“進行中”。我是否應該添加一條關於架構批准的筆記來跟蹤此決策？

跨保險庫操作

你：在工作保險庫中為我們的網站重新設計創建一個項目筆記，同時檢查我的個人保險庫中是否有任何相關的設計想法

智能體：我將在你的工作保險庫中設置一個項目筆記，並跨保險庫搜索相關內容。根據你的項目架構，我應該包括：

• 項目目標和成功標準
• 關鍵里程碑和截止日期
• 團隊成員和利益相關者
• 風險評估

這次重新設計的主要目標是什麼？

你：提高用戶參與度並將支持工單減少 30%

智能體：太棒了！我將在你的工作保險庫中創建 projects/website-redesign.md 並記錄該目標。通過跨保險庫搜索，我在你的個人保險庫中找到了 2 條相關的設計筆記，可能會對這個項目有幫助 - 我是否應該在項目筆記中引用它們？

智能元數據和組織

你：將今天的站立會議筆記添加到我的工作保險庫中

智能體：正在工作保險庫中創建你的會議筆記。我看到你有一個站立會議模板，其中包括：

• 參會人員
• 我們昨天完成了什麼？
• 我們今天要做什麼？
• 有什麼阻礙嗎？

今天的站立會議有哪些人參加？

你：整個團隊 - Sarah、Mike、Alex 和我

智能體：明白了！我將在你的工作保險庫中創建 meetings/standup-2024-01-15.md 並記錄這些參會人員和站立會議模板。使用 vault_id="work" 確保它進入正確的上下文。元數據將自動將此標記為“站立會議”，以便日後輕鬆過濾。

安全的併發更新

你：將我的項目狀態更新為已完成

智能體：我將安全地更新你的項目筆記。讓我先獲取當前版本及其內容哈希... 現在使用哈希驗證進行更新以防止衝突。✅ 項目狀態已更新為已完成，並使用內容哈希保護。

你：如果其他人正在編輯它怎麼辦？

智能體：內容哈希系統會檢測到衝突，並提醒我先獲取最新版本。這可以防止意外覆蓋其他智能體或進程所做的更改。

智能筆記重命名與跨保險庫搜索

你：將我工作保險庫中的項目筆記重命名為“網站重新設計 v2.0”，並檢查其他保險庫中是否有指向它的鏈接

智能體：我將在工作保險庫中安全地重命名你的項目筆記。讓我先獲取當前版本及其內容哈希... ✅ 使用 vault_id="work" 將項目筆記重命名為“網站重新設計 v2.0”。文件名和 ID 保持不變，因此你所有現有的鏈接仍然完美工作。

我還在所有保險庫中進行了搜索，在你的個人保險庫的日記筆記中找到了 2 條對該項目的引用。所有鏈接仍然完好。

你：這會破壞任何跨保險庫鏈接嗎？

智能體：不會！rename_note 工具僅更新顯示標題。底層文件名和標識符保持不變，因此所有維基鏈接和引用在所有保險庫中仍然有效。vault_id 參數讓我可以在不切換上下文的情況下驗證鏈接 - 所有 3 條傳入鏈接（1 條來自工作保險庫，2 條來自個人保險庫）仍然完好。

筆記類型的工作原理

flint-note 使用 筆記類型 來組織你的知識 - 每種筆記類型都有自己的用途、智能體指令和元數據架構。你的工作區看起來如下：

my-notes/
├── .flint-note/
│   └── config.yml
├── reading/
│   ├── _description.md          # 定義智能體如何處理閱讀筆記
│   ├── the-unaccountability-machine.md
├── projects/
│   ├── _description.md          # 定義智能體如何處理項目筆記
│   ├── website-redesign.md
│   └── mobile-app.md
├── meetings/
│   ├── _description.md          # 定義智能體如何處理會議筆記
│   └── team-standup-2024-01-15.md
└── daily/
    ├── _description.md          # 定義每日筆記的格式和提示
    └── 2024-01-15.md

每個 _description.md 文件告訴智能體該筆記類型的行為方式：

# 閱讀筆記

## 目的
使用結構化見解和評分跟蹤書籍、文章和論文。

## 智能體指令
- 始終詢問作者的背景和資質
- 提取關鍵見解和可操作的要點
- 請求個人評分（1 - 5 星）以及使其難忘的原因
- 建議與保險庫中其他閱讀內容的關聯
- 鼓勵提供帶有頁碼引用的具體引用

## 元數據架構
- title: 書籍/文章標題 (必需, 字符串)
- author: 作者姓名 (必需, 字符串)
- rating: 個人評分 (必需, 數字, 最小值: 1, 最大值: 5)
- status: 閱讀進度 (必需, 選擇: to_read|reading|completed)
- tags: 主題類別 (可選, 數組)
- isbn: 書籍的 ISBN (可選, 字符串)

自定義智能體行為

你可以通過與智能體對話來修改它們處理任何筆記類型的方式：

你：更新我的閱讀筆記，讓智能體始終詢問書籍的出版年份

智能體：我將更新你的閱讀筆記指令，包括詢問出版年份。

[更新 reading/_description.md 以包含新指令]

你：讓項目筆記更關注截止日期和阻礙因素

智能體：我將修改你的項目筆記指令，強調截止日期跟蹤和主動識別阻礙因素。

[相應地更新 projects/_description.md]

🔧 技術細節

直接 API 訪問

除了 MCP 服務器接口外，FlintNote 還提供了直接 API，可在不使用 MCP 協議的情況下進行編程訪問。這非常適合將 FlintNote 集成到其他應用程序或構建自定義工具。

快速開始

import { FlintNoteApi } from '@flint-note/server/api';

const api = new FlintNoteApi({
  workspacePath: './my-notes'
});

await api.initialize();

// 創建一個筆記
await api.createSimpleNote('general', 'my-note', 'Hello, world!');

// 獲取筆記
const note = await api.getNote('my-note');
console.log(note);

常見操作

// 初始化 API
const api = new FlintNoteApi({ workspacePath: './notes' });
await api.initialize();

// 創建筆記
await api.createNote({
  type: 'meeting',
  notes: [{
    type: 'meeting',
    title: 'team-standup',
    content: '# 團隊站立會議\n\n討論要點...',
    metadata: { attendees: ['Alice', 'Bob'], date: '2024-01-15' }
  }]
});

// 搜索和檢索
const results = await api.searchNotesByText('important');
const note = await api.getNote('team-standup');

// 更新內容
await api.updateNoteContent('team-standup', '更新後的內容');

// 處理保險庫
const vaults = await api.listVaults();
await api.switchVault({ vault_id: 'work' });

// 獲取統計信息
const stats = await api.getStatsResource();

可用方法

API 提供了所有核心操作的方法：

• 筆記操作：createNote、getNote、updateNote、deleteNote、searchNotes
• 筆記類型操作：createNoteType、listNoteTypes、updateNoteType
• 保險庫操作：listVaults、createVault、switchVault、getCurrentVault
• 搜索操作：searchNotes、searchNotesAdvanced、searchNotesSQL
• 鏈接操作：getNoteLinks、getBacklinks、findBrokenLinks
• 便捷操作：createSimpleNote、updateNoteContent、searchNotesByText

文檔

• 完整 API 參考：docs/API.md
• 示例：examples/api-usage.ts
• 類型定義：從 @flint-note/server 導出

從 MCP 遷移

如果你正在使用 MCP 接口，API 提供了等效的功能：

// MCP（舊方式）
const response = await client.callTool('get_note', { identifier: 'my-note' });

// 直接 API（新方式）
const note = await api.getNote('my-note');

配置

Flint Note 會自動管理其配置，並將無縫升級舊的保險庫。配置存儲在每個保險庫的 .flint-note/config.yml 中。

配置設置

關鍵配置部分包括：

• 刪除設置：控制筆記和筆記類型的刪除行為
  • require_confirmation：刪除時需要明確確認（默認值：true）
  • create_backups：刪除前創建備份（默認值：true）
  • backup_path：備份存儲位置（默認值：.flint-note/backups）
  • allow_note_type_deletion：允許刪除整個筆記類型（默認值：true）
  • max_bulk_delete：一次操作中可以刪除的最大筆記數（默認值：10）

教程

查看我們的 教程，獲取更詳細的 Flint Note 使用指南。

設計

查看 design.md 瞭解系統的設計和架構。