不建 Hugo、不用 Hexo，纯 Markdown 文件也能接入 Coco-AI！

之前我们介绍过如何通过 Coco-AI 检索 Hugo 和 Hexo 的文件结构。这种方式虽然适合博客类内容，但对于一些**零碎的笔记**或者并非建站类的 Markdown 文件，显然不够灵活。

为了解决这个问题，我写了一个适配器（connector），并发布了对应的 Docker 镜像，来实现**任意 Markdown 文件目录的元数据整理与 API 暴露**：


https://appstore.lazycat.cloud/#/shop/detail/xu.deploy.coco-ai




👉 镜像地址：[https://hub.docker.com/r/cloudsmithy/flask-markdown-connector](https://hub.docker.com/r/cloudsmithy/flask-markdown-connector)

## 核心原理

该 connector 的主要逻辑是：

1. **递归扫描目录及子目录下的 Markdown 文件**；
2. **识别或补充元数据**（即 YAML Front Matter）；
3. **通过 RESTful API 暴露这些 Markdown 的结构信息和元数据内容**。

如下图所示，我们会在每个 Markdown 文件开头添加或提取出 YAML 元数据：

![元数据展示](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328105358641.png)

## 一键部署

使用以下命令即可快速拉起服务：

```bash
docker run -d --name markdown-connector \
  -p 1313:5000 \
  -v "$(pwd):/app/markdown" \
  --restart always \
  cloudsmithy/flask-markdown-connector
```

### 参数说明：

- `-d`：后台运行容器；
- `--name markdown-connector`：指定容器名称；
- `-p 1313:5000`：将宿主机的 1313 端口映射到容器的 5000 端口；
- `-v "$(pwd):/app/markdown"`：将当前目录挂载进容器；
- `--restart always`：配置容器异常退出后自动重启；
- `cloudsmithy/flask-markdown-connector`：镜像名称。

## API 一览

通过浏览器访问 `http://localhost:1313/apidocs` 即可打开内置 Swagger 文档。方便上层系统（如 Coco-AI）访问 Markdown 文件的元数据与内容。接口结构简洁直观，支持获取索引、刷新缓存、读取内容等功能。

![Swagger 文档](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328114039208.png)

### 🔹 `GET /`

**功能**：返回服务启动提示信息  
**说明**：用于检查服务是否正常运行  
**示例响应**：

```json
{ "message": "Markdown Connector is running." }
```

### 🔹 `GET /api/posts`

**功能**：获取生成的 `index.json`（缓存版）  
**说明**：返回 Markdown 文件的路径与元数据列表，从缓存中读取，响应速度快  
**用途**：Coco Server 可用作索引加载入口  
**示例响应**：

```json
[
  {
    "title": "Docker 学习笔记",
    "path": "dev/docker.md",
    "tags": ["docker", "学习"],
    "created": "2024-11-22"
  },
  ...
]
```

### 🔹 `GET /index.json`

**功能**：实时渲染当前 Markdown 目录结构  
**说明**：等价于 `/api/posts`，但是实时读取文件而非使用缓存，适合调试或手动使用  
**用途**：确保数据为最新状态时使用

### 🔹 `GET /api/refresh`

**功能**：重新扫描并生成最新的 `index.json` 缓存  
**说明**：用于强制刷新目录索引，适用于新增 / 修改了 Markdown 文件后  
**响应示例**：

```json
{ "message": "Index cache refreshed." }
```

### 🔹 `GET /posts/`

**功能**：列出 Markdown 文件路径列表（不含元数据）  
**说明**：返回所有可访问的 Markdown 文件路径，用于构建下拉菜单、快速跳转  
**响应示例**：

```json
["notes/linux.md", "dev/docker.md", "ideas/gpt-agent.md"]
```

### 🔹 `GET /posts/{filename}`

**功能**：获取指定 Markdown 文件的内容  
**参数**：

- `{filename}`：Markdown 文件路径（相对于挂载目录）

**用途**：用于前端点击跳转后展示具体笔记内容  
**响应示例**：

```json
{
  "filename": "dev/docker.md",
  "content": "# Docker 学习笔记\n\n## 容器 vs 镜像 ..."
}
```

- 用于 Coco Server，推荐使用 `/api/posts` 作为内容索引源；
- 使用 `/api/refresh` 后再拉一次 `/api/posts` 可确保内容最新；
- 若前端需要展示具体内容，可调用 `/posts/{filename}`；
- 若用在其他 AI 项目中，也可用于构建轻量级 Markdown 知识检索接口。

## 与 Coco Server 集成

在 Orbstack 中，我们可以清晰地看到本地 Markdown 文件已经映射到容器中：

![Orbstack 文件映射](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328110115287.png)

接着我们将 connector 的服务地址填入 Coco Server 配置中：

![配置 Coco Server](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328114420941.png)

你可以使用 `/api/posts` 或 `/index.json` 接口，它们返回的内容基本一致：

- `/api/posts` 是来自缓存的接口；
- `/index.json` 是实时渲染本地文件结构。

另外，通过 `/api/refresh` 还可以手动触发缓存刷新：

![刷新缓存](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328112740320.png)

## 效果演示

成功接入后，Coco Server 就可以读取 Markdown 文件的结构与元数据信息：

![Coco 成功抓取](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328112721540.png)

点击条目还可以跳转到对应的网页：

![跳转链接](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328114249329.png)

当然，和之前一样，也支持在搜索栏中直接搜索并跳转：

![搜索跳转](https://raw.githubusercontent.com/Xu-Hardy/picgo-imh/master/image-20250328114455959.png)

## 小结

通过这个 Flask 版 Markdown Connector，我们可以将任意 Markdown 文件目录结构化暴露给 Coco-AI，实现：

- 笔记内容统一索引
- 结构与元数据清晰可控
- 快速部署，无需 Hugo/Hexo 建站

这对于日常碎片化笔记管理来说，是一个非常轻量又灵活的解决方案。