使用说明 · 导入笔记
一句话：把 Markdown 搬进笔记库 —— 粘贴或上传 .md，AI 自动生成标题、概括、评价与关键字，入库后就能被检索命中；也能挂到某篇笔记下当子笔记。整个资料目录（一篇总纲 + 若干模块 + 素材文件夹）可以一次性批量导入。 什么时候来：从顶栏「+ 导入笔记」、首页快捷入口、或笔记页「挂靠子笔记」进来；想新增一篇内容时。 适用：所有人（登录用户导入后是自己的笔记；未登录也能导入，但归属按访客身份处理）。「导入 Word」所有人可用；「目录批量导入」仅管理员可用。 更新：2026-11-13 · 对应站点 P10（Word 导入 + 目录批量导入）
0. 页面速览
| 编号 | 区域 | 干什么的 | 一句话 |
|---|---|---|---|
| ① | 页头 | 标题 + 说明 + 返回 | 一句话讲清导入流程 |
| ② | 导入 Word | .docx 转成笔记 | 选文件 → 看大纲与预览 → 入库 |
| ③ | 目录批量导入 | 整目录一次入库 | 填本机路径，服务端直接读盘（管理员） |
| ④ | 挂靠位置 | 这篇挂到哪 | 顶层，或挂到某篇笔记下当子笔记 |
| ⑤ | 可见性 | 公开 / 私密 | 私密只有你和管理员可见 |
| ⑥ | 编辑器头 | 标题 + 三个选文件按钮 | 选 .md、选图片、选文件夹 |
| ⑦ | 正文框 | 粘贴 Markdown | 支持标题、列表、表格、代码块、公式 |
| ⑧ | 底部操作 | AI 分析 / 保存入库 | 两个主按钮 |
| ⑨ | 分析结果预览 | AI 提取的元信息 | 标题、概括、评价、归类、关键字 |
| ⑩ | 小贴士 | 几条注意事项 | 支持格式、带图导入、公式 |
1. 页面结构（先认地方）
两栏布局，左边是「输入」，右边是「预览与提示」：
- 页头：标题「导入笔记」+ 一句流程说明 + 返回检索。
- 导入 Word：一条可折叠的横条，展开后选 .docx，服务端转换后先给你看大纲与 Markdown 预览。
- 目录批量导入（仅管理员可见）：一条可折叠的横条，展开后填本机路径即可整目录入库。
- 挂靠位置：一条选择器，决定这篇挂到哪。
- 可见性：公开 / 私密二选一。
- 编辑器（左栏主体）：标题框 + 三个选文件按钮 + 正文 textarea + 底部「AI 分析预览 / 保存入库」。
- 右侧栏：分析结果预览（点 AI 分析后出现）+ 最近入库 + 小贴士。
四种用法：① 直接「粘贴 Markdown」到正文框；② 点「选择 .md 文件」读文件进来；③ 一整个资料目录走「目录批量导入」；④ 单个 Word 文档走「导入 Word」。前两种在保存/分析时自动走 AI 分析；目录导入按结构批量建笔记；Word 导入先把文档转成 Markdown 再入库。
2. 功能逐条
A. 入口与前置
F1 页头
- 功能说明：标题「导入笔记」+ 副标题说明流程 + 「返回检索」按钮 + 右上角「使用说明」i 按钮。
- 功能使用方式：纯展示；点「返回检索」回首页。
- 功能作用：一眼知道这是导入入口、流程是什么。
- 其他备注：副标题写明了「粘贴或上传 Markdown → AI 自动生成 → 入库可被双路检索命中」。
- 配图：上图 ①
F2 挂靠位置（ParentPicker）
- 功能说明：选择这篇笔记挂到哪——「顶层笔记」或某篇笔记之下。
- 功能使用方式：点选择器弹出目录树，搜索并点选目标笔记；默认「顶层笔记」。
- 功能作用：导入时就定好父子关系，不用事后去层级台调。
- 其他备注：从笔记页「挂靠子笔记」进来时，这里已预置成那篇笔记。
- 配图：上图 ②
F3 可见性
- 功能说明：公开 / 私密二选一。
- 功能使用方式：点「公开」或「🔒 私密」。
- 功能作用：公开所有人可见；私密只有你和管理员可见，别人要用
@你的用户名检索才能找到。 - 其他备注：私密笔记适合还没定稿的内容。
- 配图：上图 ③
B. 输入内容
F4 标题框
- 功能说明：手动填标题，可留空让 AI 自动提取。
- 功能使用方式：输入标题，或留空。
- 功能作用：留空时 AI 会用正文第一个 H1 或内容生成标题。
- 其他备注：选 .md 文件后会自动用文件名填标题（去掉扩展名）。
- 配图：上图 ①
F5 选 .md 文件
- 功能说明：从本地选一个 Markdown / 文本文件读入。
- 功能使用方式：点「选择 .md 文件」→ 选文件 → 内容自动填进正文框、标题自动填文件名。
- 功能作用：不用复制粘贴，直接读文件。
- 其他备注：支持
.md/.markdown/.txt。 - 配图：上图 ②
F6 选图片 / 选文件夹（带图导入）
- 功能说明：如果 md 里引用了本地图片，把图片（或整个文件夹）一起选进来。
- 功能使用方式：点「选图片」选多张，或「选文件夹」选整个目录。
- 功能作用：保存时自动上传图片、把 md 里的本地路径替换成站内地址。
- 其他备注：选完 .md 后若检测到本地图片引用，会弹出一条提示条提醒你选图片。
- 配图：上图 ③④
F7 正文框
- 功能说明：粘贴或编辑 Markdown 原文。
- 功能使用方式：直接粘贴，或用 F5 读文件。
- 功能作用：这是导入的核心内容。
- 其他备注：支持标题、列表、表格、代码块、
$…$数学公式（KaTeX 渲染）。改动后右侧的分析预览会清空（需要重新分析）。 - 配图：上图 ⑤
F8 带图导入状态条
- 功能说明：检测到 md 里有本地图片引用时出现的提示条。
- 功能使用方式：按提示选图片或文件夹。
- 功能作用：提醒你别漏了图片，否则保存后图片会 404。
- 其他备注：选了图片后提示条会变绿（已选 N 个文件，保存时自动上传）。
- 配图：上图 ⑤
C. 分析与入库
F9 AI 分析预览
- 功能说明：先看 AI 提取的标题、概括、评价、归类与关键字。
- 功能使用方式：点「AI 分析预览」，右侧出现结果卡。
- 功能作用：入库前先确认 AI 提取的元信息对不对。
- 其他备注：提取 3-8 个关键字、一句话概括、AI 评价、归类。不点也能直接保存（保存时自动分析）。
- 配图：上图 ①③
F10 保存入库
- 功能说明：把内容存成一篇新笔记。
- 功能使用方式：点「保存入库」，成功后自动跳到新笔记详情页。
- 功能作用：完成导入，笔记进入检索库。
- 其他备注：带图导入会先传图再入库。标题留空时用 AI 提取的标题。
- 配图：上图 ②
F11 最近入库
- 功能说明：右侧列出最近入库的几篇笔记。
- 功能使用方式：点「打开」跳到那篇。
- 功能作用：确认库里最近在进什么，避免重复导入。
- 其他备注：纯展示，不影响导入。
- 配图：上图 ③
F12 小贴士
- 功能说明：几条注意事项。
- 功能使用方式：纯阅读。
- 功能作用：提醒支持的格式、带图导入、公式、层级调整。
- 其他备注：底部有「去层级台」快捷链接。
- 配图：上图 ③
D. 目录批量导入（仅管理员）
F13 目录批量导入
- 功能说明：把一整个资料目录（总纲 md + 各模块 md + 每篇的同名素材文件夹）一次性导进笔记库，自动建好父子层级。
- 功能使用方式：
- 点横条展开面板；
- 填服务端所在电脑上的绝对路径（例：
J:\workbuddy.workspace\ROS课程笔记）； - 点「预演」先看清单：会列出将创建几篇笔记、每篇几张图、几个附件、共多大；
- 确认无误点「开始导入」，跑完右侧直接给结果清单，点标题跳转到新笔记。
- 功能作用：
- 目录 → 层级：
NN_模块.md建一篇笔记；根目录的目录.md（或README.md/index.md）自动当父节点，其余顶层笔记挂在它下面； - 同名文件夹 → 素材：
NN_模块/里的图片转成站内资产（正文可显示），PDF/PPTX/DOCX/TXT/源码等转成附件（可下载）； - 正文链接全部改写：
→ 站内图片地址，[..](原始资料/y.pdf)→ 附件下载地址，[..](00_其它.md)→ 站内笔记地址；目录类链接（[..](某文件夹/)）退化成纯文本，不留死链； - 图片附录：默认在每篇末尾追加「附：课件插图」，把该模块
图片/里的图内联出来，可整节删除； - 只读源目录：导入过程不修改、不删除源文件。
- 目录 → 层级：
- 其他备注：
- 为什么不让浏览器上传：资料目录动辄几十 MB，公网上行只有约 100KB/s，整包上传会被网关判超时（页面报
Unexpected token '<'）。目录导入由服务端直接读盘，90MB 也就十几秒。 - 重复导入不翻倍：勾着「同父级同名笔记直接更新」时，同一目录再导一次是更新而不是新建；附件会重建，正文以源 md 为准（手工在站内改过的内容会被覆盖）。
- 会被跳过的：空文件；单文件超过 25MB；
xml / js / html这类浏览器可直接执行的类型（会改存为.txt附件，内容一字不改）。 - 导入后的结构可随时在层级台调整。
- 为什么不让浏览器上传：资料目录动辄几十 MB，公网上行只有约 100KB/s，整包上传会被网关判超时（页面报
- 配图：上图 ①②③④
E. 导入 Word（.docx）
F14 导入 Word（.docx）
- 功能说明：把 Word 文档转成一篇笔记——正文、标题层级、列表、代码、图片、表格都尽量还原。
- 功能使用方式：
- 展开「导入 Word」，点「选择 .docx」；
- 服务端自动转换（几秒到十几秒，视文档大小与是否开 AI），面板里出现统计、大纲与 Markdown 预览；
- 先看大纲对不对（标题层级错了就在源文档改样式后重传，或入库后在站内改）；
- 点「保存入库」，跳到新笔记详情页；原 .docx 自动挂成这篇笔记的附件。
- 功能作用：
- 标题层级：Word 里的「大纲级别 / 标题样式」直接映射成
#/##/###；没有样式的靠规则判（7.1.1这类编号 + 加粗 + 短行），再交给 AI 复核； - 代码块：Word 里用「单列表格」或等宽样式做的代码框，会还原成带语言标注的代码块，缩进原样保留（这点 pandoc 做不到，实测会丢全部缩进）；
- 表格：普通表格转成 Markdown 管道表（合并单元格降级为留空）；
- 图片：文档内嵌图片抽出来存成站内图片，正文里就地显示；
- AI 只贴标签：勾选「AI 判标题层级与代码语言」时，AI 只回答「这块是什么角色、代码是什么语言」，正文一个字都不经过它改写，所以不会丢字或走样。
- 标题层级：Word 里的「大纲级别 / 标题样式」直接映射成
- 其他备注：
- 公式（OMML）暂按纯文本保留，不转 LaTeX；正文会提示有几处公式。
- 上传上限 8MB：公网上行只有约 100KB/s，更大的文件请用「目录批量导入」（服务端直接读盘）。
- 不支持
.doc旧格式，请先在 Word 里另存为.docx。 - 转换是「预览 / 入库」两步：预览不会在库里留下笔记；图片资产会先落盘（内容哈希命名，重复导入不会重复占空间）。
- 扫描件（整页图片的 Word）不会有文字，需要 OCR，本页不支持。
- 配图：上图 ①②③④
3. 常见任务（照着做）
| 想做什么 | 怎么做 |
|---|---|
| 导入一篇 Markdown | 粘贴到正文框（或选 .md 文件）→「保存入库」 |
| 导入前先看 AI 提取对不对 | 粘贴 →「AI 分析预览」→ 看结果 → 保存 |
| 导入一篇带图的 md | 选 .md → 按提示「选图片」或「选文件夹」→ 保存 |
| 导入一个 Word 文档 | 展开「导入 Word」→ 选 .docx → 看大纲与预览 →「保存入库」 |
| Word 里的代码想保留缩进 | 用「导入 Word」而不是复制粘贴——单列表格/等宽样式的代码框会还原成代码块 |
| 导入一整套课程资料（多篇 + 素材） | 展开「目录批量导入」→ 填本机路径 →「预演」→「开始导入」 |
| 重新导入同一目录（源文件改过） | 同上，保持「同父级同名笔记直接更新」勾选 →「开始导入」 |
| 挂到某篇笔记下 | 「挂靠位置」点开选目标笔记 → 保存 |
| 导入成私密笔记 | 「可见性」切「🔒 私密」→ 保存（目录导入走的是账号默认公开） |
| 让 AI 自动起标题 | 标题框留空 → 保存（或分析） |
4. 本页没有的功能（省得白找）
- 没有富文本编辑：正文是纯 Markdown 文本，没有所见即所得排版。
- 单篇导入一次只能一篇：要整目录请用「目录批量导入」（管理员），它才是批量入口。
- 目录导入不盯盘：不是监视文件夹实时同步，源文件改了要再点一次导入。
- 没有导入后原地编辑：保存后会跳到新笔记详情页，编辑要去详情页或设置页。
- 没有导入历史记录：右侧「最近入库」只是最近几篇，不是完整的导入历史。
- 没有 OCR / 图片转文字：只支持文本 Markdown 与 .docx 的文本层，不能从扫描件/截图提取文字。
- 没有 Word 公式转换：.docx 里的公式（OMML）按纯文本保留，不会变成
$...$。 - 不支持 .doc 旧格式：请先另存为 .docx。
- Word 导入不保留版式：字体、字号、颜色、页眉页脚、批注、图文绕排都会丢掉——Markdown 没有这些概念。
- 没有自动同步文件夹：选文件夹只是把图片读进来，不是监视目录实时同步。
5. 相关页面
- 笔记详情（
/note/<id>/）：导入成功后跳到这里看正文。 - 层级台（
/tree/）：事后调整父子层级。 - 检索首页（
/）：导入的笔记能在这里被双路检索命中。 - 笔记设置（
/note/<id>/settings/）：导入后改可见性、源码、授权。