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 了解系统的设计和架构。