采集与导入

采集解决的是「先把内容收进来，再慢慢整理」。入口是收集箱（inbox）：收集箱内容不参与 AutoLink 实体抽取与建链，等你升格为正式笔记（note）时才自动补抽，不会污染知识网络。

收集箱快速采集

应用内的收集箱自带快速采集入口：粘贴一段文字或一个链接，回车即存入。整理完成后一键升格为正式笔记，或批量归档、清空。

桌面端打开即导入

双击 .md 文件用 NoteFast 打开，内容直接导入知识库，按路径与内容哈希去重——同一个文件重复打开不会产生重复文档。该通道对应导入契约中的 file-open provider。

HTTP 导入端点

脚本、快捷指令类工具或任何 HTTP 客户端都可以走统一的导入端点：

POST /api/v1/import/markdown
Authorization: Bearer <api_token>
Content-Type: application/json

字段	必填	说明
markdown	✓	正文（≤ 5MB）
title		缺省取首个 H1，否则「未命名文档」
status		'inbox'（收集箱）或 'note'，缺省 'note'
tags		字符串数组，入库前自动规范化（小写、空白转连字符）
notebook_id		缺省入第一个笔记本
source		{ provider, external_id }，见下节

响应：成功创建返回 201 {doc, block_count, ...}；去重命中返回 200 {doc, deduplicated: true}（零副作用）。

source 与去重语义

source 是外部内容的身份。携带 source 的导入：

• 同 provider + external_id 且内容一致 → 去重返回既有文档，无任何副作用
• 内容变了 → 新建一篇进收集箱；旧文档保留你的编辑、剥掉 source 成为普通笔记，source 锚定最新篇
• 回收站里的旧导入不阻挡重新导入

provider 命名约定：file-open 已被桌面端「打开即导入」占用，自建通道请自取新名。external_id 网页类内容建议用规范化 URL（去 hash、去 utm_* 跟踪参数）。

示例：

curl -X POST "https://your-host/api/v1/import/markdown" \
  -H "Authorization: Bearer nf_xxx" \
  -H "Content-Type: application/json" \
  -d '{"markdown":"正文内容","title":"...","status":"inbox","source":{"provider":"my-script","external_id":"https://example.com/page"}}'

大文件（>5MB）请走 MCP 的分块暂存通道（notefast_stage_markdown + notefast_create_doc_from_file，见 MCP 集成）。

安全：对外暴露该端点时，务必使用设置页生成的可撤销令牌（权限最小化，read + write），不要用主 API_TOKEN；泄露时在令牌列表撤销即可。

规划中

浏览器 Bookmarklet 与 iOS 快捷指令两个官方采集通道正在规划中，尚未发布。在此之前，上述 HTTP 端点已能覆盖同类需求。