一条命令把笔记变成知识库：Markdown上传实战教程

一条命令把笔记变成知识库：Markdown笔记上传灏天文库实战教程

为什么要做这件事？

如果你正在读这篇文章，你大概率属于以下几类人之一：

• 用 Obsidian / Notion / Typora / Logseq 等工具记了大量笔记，但笔记只是躺在本地
• 写了很多技术学习笔记，想分享给更多人但不知道用什么平台
• 团队需要一个统一的知识管理平台，但市面上的工具要么太重要么太贵
• 想把自己的笔记变成可搜索、可展示、可引用的知识库

这篇文章会手把手教你如何用最简单的方式——一条命令——把你的 Markdown 笔记上传到灏天文库，让它从"私人笔记"变成"公开知识资产"。

什么是灏天文库？

灏天文库（aiknowledge.cn）是一个人工智能与泛技术领域的知识平台。它提供文集管理、文档上传、全文搜索和 RAG 智能检索等能力。

简单说，它做的事情是：

• 你写好的内容（Markdown 格式），上传后自动变成排版精美的在线文档
• 支持创建文集，把相关主题的笔记组织在一起
• 上传的文档支持全文搜索和向量检索，别人能精准找到你的内容
• 每篇文档有固定链接，方便分享和引用

准备工作：确保你的笔记是Markdown格式

在开始之前，先确认你的笔记格式。

如果你用 Obsidian：直接可用。Obsidian 的笔记就是 .md 文件。

如果你用 Typora：直接可用。Typora 本身就是 Markdown 编辑器。

如果你用 Notion：需要导出。页面右上角 → Export → 选择 Markdown & CSV。

如果你用 Logseq：Logseq 的笔记存储在本地 journals/ 和 pages/ 目录下，直接复制 .md 文件即可。

如果你用思源笔记：需要导出为 Markdown 格式。

如果你用飞书 / 语雀：支持导出为 Markdown。

核心操作：一条命令上传

灏天文库提供了 ht-skills 技能包，其中的 add_document.py 脚本就是上传工具。

基本用法：

python scripts/add_document.py \
  --collection-id <文集ID> \
  --name "文档标题" \
  --content-file /path/to/your/note.md
​

就这么简单。一个 Python 脚本，三个参数，笔记就上线了。

如果你是直接传入文本内容，也可以：

python scripts/add_document.py \
  --collection-id <文集ID> \
  --name "文档标题" \
  --content "这里是正文内容"
​

获取文集ID

上传前你需要知道目标文集的 ID。查看文集列表：

python scripts/list_collections.py --name "关键词"
​

比如搜索"Python"相关的文集：

python scripts/list_collections.py --name "Python"
​

返回结果中会包含文集的 ID、名称和描述。记录下你想上传到的文集 ID。

如果还没有文集，可以新建：

python scripts/create_collection.py \
  --name "我的技术笔记" \
  --description "日常技术学习笔记整理"
​

实战案例一：上传Obsidian笔记到灏天文库

场景：我在 Obsidian 中有一篇关于 Python 装饰器的笔记 decorator.md，想上传到"Python学习"文集中。

步骤：

1. 确认文集 ID：

python scripts/list_collections.py --name "Python"
# 返回 id: 123
​

2. 上传笔记：

python scripts/add_document.py \
  --collection-id 123 \
  --name "Python装饰器详解" \
  --content-file ~/my-vault/notes/decorator.md
​

3. 完成。笔记已上传，可以在灏天文库平台查看。

实战案例二：批量上传Notion导出的笔记

场景：从 Notion 导出了 20 篇 Markdown 文件到一个目录 ~/notion-export/，想批量上传。

步骤：

1. 创建目标文集：

python scripts/create_collection.py \
  --name "Notion笔记归档" \
  --description "从Notion迁移的笔记集合"
# 返回 id: 456
​

2. 写一个简单的批量上传脚本：

#!/bin/bash
COLLECTION_ID=456
EXPORT_DIR=~/notion-export

for file in "$EXPORT_DIR"/*.md; do
  filename=$(basename "$file" .md)
  python scripts/add_document.py \
    --collection-id $COLLECTION_ID \
    --name "$filename" \
    --content-file "$file"
  echo "已上传: $filename"
done
​

3. 执行脚本，等待批量上传完成。

实战案例三：创建体系化知识结构

场景：你有多领域的笔记，想按主题分别建文集上传。

# 创建文集
python scripts/create_collection.py --name "AI学习笔记" --description "人工智能领域学习笔记"
# id: 301

python scripts/create_collection.py --name "后端开发" --description "Python/Go/Java后端技术笔记"
# id: 302

python scripts/create_collection.py --name "运维工具" --description "Docker/K8s/CI-CD等运维笔记"
# id: 303

# 上传对应笔记
python scripts/add_document.py --collection-id 301 --name "Transformer架构详解" --content-file ~/notes/transformer.md
python scripts/add_document.py --collection-id 302 --name "Go并发编程" --content-file ~/notes/go_concurrency.md
python scripts/add_document.py --collection-id 303 --name "Docker Compose入门" --content-file ~/notes/docker_compose.md
​

这样，你的知识就有了清晰的组织结构。

上传后还能做什么？

全文搜索：上传的文档会被纳入全文索引，你可以用关键词搜索到自己的笔记。

RAG 检索：文集开启 RAG 后，支持语义级别的智能检索，即使用词不同也能匹配到相关内容。

文档更新：文档上传后随时可以修改内容：

python scripts/update_document.py \
  --id <文档ID> \
  --content "更新后的内容"
​

文档管理：支持移动文档到其他文集、修改排序、设置父子关系等操作。

技巧与建议

保持 Markdown 格式规范：建议使用标准的 Markdown 语法，避免使用特定编辑器的私有语法（如 Obsidian 的 ![[双向链接]]），因为上传到平台后私有语法不会被解析。

合理使用标题层级：用 H2 和 H3 组织内容结构，不要跳级。良好的层级结构不仅可读性好，对检索和展示也友好。

代码块标注语言：写技术笔记时，代码块记得标注语言类型（```python），这样在平台上会有语法高亮。

图片使用在线链接：如果笔记中包含图片，建议使用在线图片链接而非本地路径，确保上传后图片能正常显示。

分文集管理：不同主题的笔记放在不同文集里，方便管理和检索。不要把所有笔记都堆在一个文集里。

定期上传：养成定期把新笔记上传到平台的习惯。知识管理的价值在于持续积累。

从"笔记"到"知识资产"的转变

传统的笔记软件解决的是"记录"问题——帮你把信息存下来。

灏天文库解决的是"展示和分享"问题——让你的知识可以被搜索、被发现、被引用。

这两个能力结合在一起，才是完整的知识管理闭环：

• 记录：用你最顺手的笔记软件（Obsidian、Notion、Typora……）
• 整理：保持 Markdown 格式，按主题分类
• 发布：一条命令上传到灏天文库
• 检索：全文搜索 + RAG 向量检索，精准定位内容
• 分享：链接分享，让知识流动起来

你写的每一条笔记，都不应该只是"本地文件"。它们是知识，值得被更好地利用和展示。

常见问题

Q：ht-skills 支持哪些 Python 版本？

Python 3.6 及以上版本均可使用。建议使用 Python 3.8+。

Q：上传的文档支持富文本排版吗？

灏天文库会将 Markdown 渲染为富文本格式，包括标题层级、列表、代码高亮、表格等。

Q：上传失败怎么办？

检查 Markdown 文件编码是否为 UTF-8，确认文集 ID 是否正确，确认网络连接正常。

Q：如何修改已上传的文档？

使用 update_document.py --id <文档ID> --content "新内容" 即可更新。

Q：可以删除已上传的文档吗？

可以通过文档管理接口操作。建议上传前确认内容质量。

Q：支持哪些内容类型？

支持技术文章、学习笔记、教程、案例分析等各类 Markdown 格式的文本内容。