> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用笔记

> 在 Chatbot 窗口里随手写卡片笔记，存成本地 Markdown 文件，可以被搜索、被 AI 读写，也能用任意编辑器打开。

## 什么是笔记

Linkly AI 的**笔记**是一串按时间排列的小卡片：想到什么就在底部输入框里敲一句，回车存下，它立刻变成时间线上的一张卡片。

和其他笔记软件最大的不同是——**每张卡片就是磁盘上一个普通的 `.md` 文件**。没有专有数据库，没有导出功能（因为不需要），你随时可以用 Obsidian、VS Code 打开它们，也可以直接 `grep`。同时它们会被 Linkly AI 索引，能被搜索到，也能被你的 AI 助理读写。

<CardGroup cols={2}>
  <Card title="快到不用想" icon="bolt" iconType="duotone">
    输入框常驻在底部，写完 ⌘/Ctrl+Enter，不用新建文件、不用起标题
  </Card>

  <Card title="就是本地文件" icon="file-lines" iconType="duotone">
    标准 Markdown + YAML 头，任何编辑器可读可改，删了应用也还在
  </Card>
</CardGroup>

### 适合记什么

笔记的定位是**短、快、事后能找到**，不是写长文：

* **临时想到的事**：一句话待办、突然冒出的产品点子
* **读文档时的批注**：一边让 AI 检索资料，一边把结论顺手记下来
* **让 AI 沉淀的结论**：让 Chatbot 读完一批资料后，把要点直接写成一条笔记
* **零散信息的落脚点**：会议里听到的一个数字、别人推荐的一本书

如果你要写的是一篇正经文档，直接在 `~/LinklyAI` 目录里新建 Markdown 文件更合适——它同样会被索引。

***

## 打开笔记

笔记**不是一个独立窗口**，而是 Chatbot 窗口里的一个视图，和对话并列：

* 点击 Chatbot 左侧栏的「**笔记**」按钮
* 或按 **⌘⇧N**（Windows / Linux：**Ctrl+Shift+N**）

<Warning>**⌘⇧N 不是全局快捷键**——必须先让 Chatbot 窗口处于前台、拿到焦点，按下才有反应。整个应用唯一的全局快捷键是 **⌘⇧L / Ctrl+Shift+L**（唤起[搜索启动器](/docs/zh/use-launcher)）。</Warning>

***

## 写第一条笔记

<Steps>
  <Step title="在底部输入框里写">
    笔记视图底部有一个常驻输入框，占位提示是「记点什么…用 #标签 打标签」。

    正文长的时候点右上角的展开按钮，输入框会**原地向上增高**（最高到窗口的 60%），不会弹出新窗口，草稿和光标位置都不受影响。
  </Step>

  <Step title="保存">
    按 **⌘/Ctrl+Enter**，或点右下角的发送按钮。卡片会立刻出现在时间线底部。

    <Note>
      单纯按 Enter 是换行，不会保存——这是刻意的，笔记经常要写好几行。
    </Note>
  </Step>

  <Step title="改">
    在卡片上点「编辑」，卡片会**原地变成可编辑状态**，不弹对话框。同一时刻只能编辑一张卡片。

    改完必须点「**保存**」或按 ⌘/Ctrl+Enter。
  </Step>

  <Step title="删">
    卡片右上角 `⋯` 菜单 → 删除 → 二次确认。
  </Step>
</Steps>

<Warning>**删除是永久删除磁盘上的那个文件**，不进回收站，应用里也没有撤销。确认框上写得很清楚：「将从磁盘永久删除该笔记文件，不可撤销。」</Warning>

### 编辑器能做什么

笔记编辑器是一个**纯 Markdown 文本框**，不是富文本——你看到的就是源码。工具栏只有 5 个按钮：

| 按钮     | 作用                    |
| ------ | --------------------- |
| 加粗     | 给选中文字套 `**`           |
| 删除线    | 给选中文字套 `~~`           |
| 无序列表   | 把选中行变成 `-` 列表         |
| 有序列表   | 把选中行变成 `1.` 列表        |
| 插入 Tag | 在光标处插入 `#`，同时唤起标签自动补全 |

**没有**斜体、标题、链接、代码块按钮——这是有意收窄的，笔记就该短。在列表里按回车会自动延续下一项。

保存后卡片进入阅读态，会正常渲染 Markdown。

<Warning>**没有自动保存。**输入框和编辑器里的内容只存在内存里：切换到对话视图再切回来草稿还在，但**关掉应用就没了**。写完记得按 ⌘/Ctrl+Enter。</Warning>

<Note>
  阅读态里**图片不会联网加载**，只显示一个带 alt 文字的占位块。这是隐私设计——渲染一张远程图片等于向对方服务器泄露"你在这一刻读了这条笔记"。

  界面上没有字数限制，后端上限是单条 10 MiB，日常写不到。
</Note>

***

## 标签

在正文里直接写 `#标签` 就是打标签。输入 `#` 会弹出候选列表（最多 8 条），↑↓ 选择、Enter 确认。

保存后，标签会从正文中被摘出来，显示在卡片底部的标签条上——点击任意一个就能筛出所有带这个标签的笔记。

标签支持用 `/` 分层，比如 `项目/客户A`、`读书/技术`。单条笔记最多 50 个标签，单个标签 1–64 个字符。

<Warning>\*\*界面上没有独立的标签输入框，标签只能写在正文里。\*\*这也意味着：想删掉某个标签，就把正文里那段 `#标签` 删掉——正文是唯一的事实来源。</Warning>

***

## 找到一条笔记

### 时间线

笔记视图是一条**扁平的卡片流，没有按日期分组**。展示顺序恒定是「**旧的在上、新的在下**」，和聊天记录一样——最新的那条永远在你眼皮底下。每次加载 20 条，往上滚可以「加载更早」。

### 排序

顶部的排序菜单有三档：

| 排序       | 含义               |
| -------- | ---------------- |
| **最新创建** | 默认。按创建时间，新的排在最后面 |
| **最早创建** | 反过来              |
| **最新编辑** | 按最后修改时间排         |

<Note>排序是**会话级**的——关掉应用不保存，下次打开回到「最新创建」。</Note>

### 搜索

点顶部的放大镜，或按 **⌘/Ctrl+F**。

搜索不是简单的子串匹配，走的是 Linkly AI 的全文检索（建好语义索引时是关键词 + 语义混合，否则是纯关键词）。所以搜"发布计划"也可能命中写着"上线安排"的笔记。

<Note>搜索**最多返回 20 条结果，没有分页**。想收窄范围，先点一个标签过滤再搜。输入有约 0.3 秒的防抖，停手才会真正发起查询。</Note>

### 为什么刚写的笔记搜不到

这是最容易困惑的一点。笔记视图上的三块内容走的是**三条不同的数据通路**，时效不一样：

| 你在看的东西       | 数据从哪来      | 新建笔记后    |
| ------------ | ---------- | -------- |
| 时间线、标签过滤     | 直接扫描文件系统   | **立刻可见** |
| 全文搜索结果       | 依赖索引       | 有延迟      |
| 输入 `#` 的补全候选 | 依赖索引派生的标签表 | 有延迟      |

所以「刚写的笔记在时间线里看得见，但搜不到、`#` 补全里也没有」是**正常现象**，等索引跑完就好了。反过来，时间线永远是最新的——它根本不查索引。

***

## 笔记存在哪里

所有笔记都在你的资料库根目录（默认 `~/LinklyAI`）下的 `Notes/` 里，按月分文件夹：

```
~/LinklyAI/Notes/
├── 2026-06/
│   └── 周会记录整理-3ea26713.md
└── 2026-07/
    ├── Launch待办清单-91805137.md
    └── 2026-07-28-080741-ca478cef.md
```

月份目录按 **UTC** 计算，所以月初/月末写的笔记，落到哪个月目录可能和你本地时区差一天。

### 文件名规则

文件名是 `<正文前 10 个字>-<笔记 id 前 8 位>.md`：

* 前 10 个字按 **Unicode 字符**计，中文一个字算一个
* 连续空白折叠成一个空格，并计入这 10 个字
* 文件系统非法字符（`/ \ : * ? " < > |`）会被剔除，且**不计入**字数

举个真实例子：正文第一行是 `**Launch待办清单**` 的笔记，`*` 被剔除不计数，于是取到 `Launch待办清单` 这 10 个字，文件名是 **`Launch待办清单-91805137.md`**。

如果正文全是符号或空白（取不出词干），或者恰好撞上 Windows 保留名（`CON`、`NUL` 之类），就回退成时间戳命名：`YYYY-MM-DD-HHMMSS-<8位id>.md`。

<Note>\*\*文件名在创建时定名，之后编辑正文不会改名。\*\*这样文件的身份是稳定的，索引和外部引用不会因为你改了个错别字就全部失效。</Note>

### 文件格式

每个文件就是标准 Markdown，头部带一段 YAML front matter：

```markdown theme={null}
---
note_id: 91805137-c3f8-4bc9-8db4-e7e8d99409bc
created_at: 2026-07-28T08:02:21.095Z
updated_at: 2026-07-28T08:05:33.709Z
source: user
updated_by: user
tags:
  - 测试
---

**Launch待办清单**

发布前要确认的事：

- 官网文案定稿
- 更新日志三语翻译
- 各下载站提交

#测试
```

字段含义：

| 字段                                | 说明                              |
| --------------------------------- | ------------------------------- |
| `note_id`                         | 笔记的唯一 ID（UUID），文件名末尾那 8 位就取自它   |
| `created_at` / `updated_at`       | 创建时间 / 最后修改时间，ISO 8601、毫秒精度、UTC |
| `source`                          | 这条笔记由谁创建：`user`（你）或 `agent`（AI） |
| `agent`                           | 仅 AI 创建时出现，标明是哪个 Agent          |
| `updated_by` / `updated_by_agent` | 最后一次修改由谁做出，取值同上                 |
| `tags`                            | 标签数组                            |

字段顺序是固定的。**你手动加进去的未知字段会被原样保留**，应用不会删掉它们——想塞自己的元数据是安全的。

AI 写的笔记长这样，界面上会带一个 `AI` 徽章：

```yaml theme={null}
source: agent
agent: linkly-chatbot # 应用内置 Chatbot；外部 Agent 写入时是 external-mcp
updated_by: agent
updated_by_agent: linkly-chatbot
```

***

## 用其他编辑器打开

顶部有个「**打开笔记文件夹**」按钮，会在系统文件管理器里直接打开 `Notes/` 目录。

因为就是标准 Markdown，Obsidian / VS Code / Typora 都能直接读写。`tags:` 这个字段恰好是 Obsidian 原生识别的，把 `Notes/` 作为 Vault 打开就能用它的标签面板。

外部改动之后，应用下次扫描会感知到。如果你**正好在应用里编辑同一条**，会弹出冲突提示让你选择「重新载入」或「复制我的内容」——**不会静默覆盖**你的任何一边。

你也可以自由重命名文件，应用不会改回去。

<Warning>
  两个会让笔记「消失」的操作，注意避开：

  1. \*\*时间线只扫描 `Notes/YYYY-MM/` 这两级结构里的 `.md`。\*\*放在 `Notes/` 根目录、或 `Notes/archive/` 这类其他子目录里的文件，**不会出现在时间线上**（但仍会被全文索引，还是能搜到）。
  2. **删掉 YAML 头**，这条笔记就从时间线消失了——文件还在磁盘上，也还能搜到，只是应用不再把它当作一条笔记。
</Warning>

***

## 让 AI 帮你记笔记

笔记可以被 AI 助理读写。本地 MCP 提供两个工具：

| 能力   | MCP 工具      | CLI 命令                      |
| ---- | ----------- | --------------------------- |
| 写笔记  | `note_save` | `linkly note-save`          |
| 列出笔记 | `list`      | `linkly list --scope notes` |

完整参数见[使用 CLI](/docs/zh/use-cli)。配置 MCP 见[连接 AI 工具](/docs/zh/use-mcp)。

直接用自然语言指挥就行：

<CardGroup cols={1}>
  <Card title="写一条" icon="pen" iconType="duotone" horizontal>
    "把刚才这段结论记成一条笔记，打上 产品 和 待办 两个标签"
  </Card>

  <Card title="先读再写" icon="wand-magic-sparkles" iconType="duotone" horizontal>
    "读一下我 ml-papers 知识库里关于 attention 的资料，把要点整理成一条笔记"
  </Card>

  <Card title="翻旧账" icon="clock-rotate-left" iconType="duotone" horizontal>
    "列出我带 ops 标签的笔记"
  </Card>
</CardGroup>

有几条差异需要知道：

* \*\*编辑要带版本号做并发校验。\*\*AI 编辑一条笔记时必须带上读到的 `version`，如果这期间笔记被改过，写入会被拒绝（`NOTE_VERSION_CONFLICT`），而不是盲目覆盖。
* **AI 写笔记的正文格式受限**：只允许段落、加粗、删除线、有序/无序列表和纯文本——和界面工具栏的能力一致。标题、斜体、代码块、链接、图片、表格会被拒绝。**你自己在界面里手写不受这个限制。**
* \*\*MCP 没有删除工具。\*\*删除笔记只能在应用界面里做。
* **标签规则不一样**：这条路径**不提取正文里的 `#标签`**，只认显式传入的标签参数；而且编辑时标签是**全量替换**，没写上的会被删掉。

<Warning>**已知问题**：AI 通过 MCP 写完笔记后，界面不会自动刷新，需要切到对话视图再切回笔记才看得到（[issue #172](https://github.com/LinklyAI/linkly-ai-desktop/issues/172)）。</Warning>

***

## 常见问题

<AccordionGroup>
  <Accordion title="笔记会同步到云端吗？">
    Notes 目前**没有专属的云同步功能**，笔记以本地文件的形式保存在你的资料库目录里。

    需要留意的是：如果你把 `Notes/` 目录加进了某个知识库，而这个知识库又绑定并推送到了[云端知识库](/docs/zh/use-cloud-library)，那笔记会像其他 Markdown 文档一样被上传。想完全留在本地，就别把 `Notes/` 放进要推送的知识库。
  </Accordion>

  <Accordion title="按了 ⌘⇧N 没反应？">这个快捷键**只在 Chatbot 窗口聚焦时**生效，不是全局快捷键。先点一下 Chatbot 窗口再按。全局唯一可用的是 ⌘⇧L / Ctrl+Shift+L（唤起搜索启动器）。</Accordion>

  <Accordion title="刚写的笔记搜不到，是丢了吗？">没丢。时间线直接扫文件系统，所以立刻可见；全文搜索走索引，有延迟。等索引跑完就能搜到了。同理，新标签也要等一会儿才会出现在 `#` 的补全候选里。</Accordion>

  <Accordion title="能不能给笔记置顶 / 收藏 / 归档 / 导出？">目前都没有。置顶、收藏、归档暂时不在功能里；导出则是不需要——笔记本身就是磁盘上的 `.md` 文件，复制走就行。有归档需求的话，可以在外部编辑器里把文件挪到别的目录，但注意它会从时间线上消失（详见[用其他编辑器打开](#用其他编辑器打开)）。</Accordion>

  <Accordion title="AI 写的笔记，标签在界面上改不动？">
    是已知问题（[issue
    \#171](https://github.com/LinklyAI/linkly-ai-desktop/issues/171)）。MCP / CLI
    这条路径不提取正文里的 `#标签`，只写显式传入的标签参数——结果就是标签存在 YAML
    里、正文里却没有对应的 `#标签`，而界面改标签是靠改正文的，于是改不动。

    临时办法：用外部编辑器直接改文件的 `tags:` 字段，或者在正文里补上对应的 `#标签` 再在界面里保存一次。
  </Accordion>

  <Accordion title="删掉的笔记能找回来吗？">不能。删除是直接删磁盘上的文件，不进系统回收站，应用里也没有撤销。删之前想清楚，或者先用外部编辑器备份一份。</Accordion>

  <Accordion title="笔记会被算进知识库的文档数量吗？">
    会。笔记是 `~/LinklyAI` 目录下的普通 Markdown 文件，和其他文档一样被扫描、索引、参与检索——所以你也能在[搜索启动器](/docs/zh/use-launcher)里搜到它们，AI 助理用 `search` 也能命中。
  </Accordion>
</AccordionGroup>

***

## 延伸阅读

* [使用启动器](/docs/zh/use-launcher) —— 全局搜索，笔记同样能被搜到
* [使用 CLI](/docs/zh/use-cli) —— `note-save` / `list --scope notes` 的完整参数
* [连接 AI 工具](/docs/zh/use-mcp) —— 让外部 AI 助理读写你的笔记
* [工具介绍](/docs/zh/tools-intro) —— MCP 工具的完整说明
* [使用 AI 对话](/docs/zh/use-chatbot) —— 笔记所在的那个窗口还能做什么
* [Linkly AI 空间](/docs/zh/linkly-space) —— `Notes/` 所在的目录，以及怎么改它的位置