VIHUB 学习站：用语雀 MCP + Agent 把笔记写进网站源码

适用对象：站点维护老师（可直接改 edu.vihub.cn 原代码） 核心思路：语雀用 MCP 读稿 → Agent 整理成 Markdown → 写入网站仓库并部署 不需要浏览器代点「发布页」，也不依赖网站后台表单。

站点入口：https://edu.vihub.cn/ 笔记栏目：https://edu.vihub.cn/note

1. 这套流程在干什么

语雀知识库（已有笔记）
        │
        │  Agent + yuque MCP（搜索 / 拉文档 / 取 Markdown）
        ▼
本地 Markdown 文件（或网站约定的 notes 目录）
        │
        │  按项目现有规范改路由、列表、模板（如需要）
        ▼
提交 / 部署 → edu.vihub.cn/note 对学生可见

和「登录网站后台点发布」的区别：

2. 一次性准备

2.1 语雀 Token

1. 打开：https://www.yuque.com/settings/tokens
2. 新建 Token（建议至少具备：读个人/团队文档、读知识库）
3. Token 只保存在本机，不要发到学生群、不要截图外传

2.2 给 Cursor（或 Codex）接通语雀 MCP

本机已装 Node.js（≥ 18）时，执行：

npx yuque-mcp install --token=你的TOKEN --client=cursor

然后完全退出并重启 Cursor。

自检（新开对话对 Agent 说）：

请调用语雀 MCP 的 yuque_get_user，告诉我当前语雀用户名。

能返回正确账号，说明 MCP 可用。

仓库与说明：https://github.com/yuque/yuque-mcp-server

2.3 准备网站源码仓库

1. 在本机打开 VIHUB 网站项目（Git 仓库）
2. 先和老师自己确认：笔记 Markdown 应该放在哪个目录（见下一节「目录约定」）
3. 能本地预览、能部署到 edu.vihub.cn（原有部署方式不变：FTP / Git / 服务器脚本等）

3. 建议的源码约定（老师可按现有项目微调）

若项目里还没有统一约定，建议采用下面结构（Agent 也好认）：

网站仓库/
  notes/                          # 对外技术笔记（Markdown 源）
    shell/
      01-什么是Shell编程及环境搭建.md
      08-脚本参数与选项解析.md
    java/
      ...
  templates/ 或 pages/            # 列表页、详情页（按现有框架）
  static/

单篇 Markdown 建议文件头（YAML front matter，方便列表页自动读标题/分类）：

---
title: 第8节：脚本参数与选项解析
category: Shell编程
date: 2026-09-15
author: Monte
yuque_url: https://www.yuque.com/xxx/xxx/xxx
status: published
---

# 第8节：脚本参数与选项解析

正文……

若网站目前是「数据库存笔记」而不是「读 MD 文件」：

• 方案 A（推荐长期）：改成读 notes/**/*.md 生成列表/详情（一次改造，以后 Agent 只写 MD）
• 方案 B（短期）：Agent 仍生成 MD，老师或脚本再导入数据库 本手册按 方案 A：源码里就是 MD 来写操作话术。

4. 标准操作流程（单篇）

步骤 1：语雀侧定稿

在语雀把笔记改到可以给学生看，标题清晰。可选在文首加：

【发布到】edu.vihub.cn/note
【分类】Shell编程
【状态】待发布

步骤 2：打开网站仓库 + 打开 Agent

在 Cursor 中打开网站源码根目录（不是随便一个空文件夹）。

步骤 3：让 Agent 从语雀拉出 Markdown（先不改仓库）

复制发给 Agent：

请使用语雀 MCP：
1. 搜索 / 打开文档：《这里换成语雀文档标题》
2. 用 yuque_get_doc 拉取全文，格式 markdown
3. 清洗：去掉【状态】等内部标记、私有评论、不适合公开的内容
4. 按本仓库 notes/ 的规范整理成一篇 MD（含 YAML 头：title、category、date、yuque_url）
5. 先把完整 Markdown 在对话里发给我预览，不要写文件，等我确认

步骤 4：老师确认内容

检查：标题、分类、代码块、图片链接、有无内部信息。

步骤 5：写入源码

确认后对 Agent 说：

内容确认。请写入本仓库：
notes/<分类目录>/<序号-标题>.md
若列表页/路由需要登记新文件，请按现有代码风格一并改好（不要无关重构）。
改完列出：新增/修改了哪些文件。

步骤 6：本地看一眼 → 部署

# 按老师原有方式，例如：
git add notes ...
git commit -m "docs(note): 新增 Shell 第8节"
git push
# 或执行项目里的 deploy 脚本 / 上传到服务器

浏览器打开 https://edu.vihub.cn/note 验收。

步骤 7：回写语雀状态（可选）

把语雀文档标成「已发布」，并贴上网站链接。也可用 Agent：

用语雀 MCP 打开刚才那篇文档，把文首【状态】改为已发布，并追加一行网站地址：……
（若 Token 无写权限则跳过，我自己改语雀）

5. 批量发布流程（一门课多篇）

请用语雀 MCP：
1. 列出知识库「……」中状态含「待发布」的全部文档
2. 按「第N节」或更新时间排序
3. 生成计划表：序号 | 语雀标题 | 建议文件名 | 分类 | 是否有图/附件风险
先不要写任何本地文件。

老师确认计划后：

按计划从第 1 篇开始，严格「一篇一确认」：
拉语雀 → 对话里预览 → 我回复「本篇确认」后再写入 notes/ → 再下一篇。
全部完成后给出：语雀链接 ↔ 本地文件路径 ↔ 上线后 URL 对照表。

最后老师统一 commit + 部署一次即可。

6. 可直接复制的提示词卡片

只读预览

用语雀 MCP 取出《文档名》的 markdown，改写成适合 notes/ 的技术笔记，先发我预览，不要写文件。

确认后落盘

写入 notes/shell/08-脚本参数与选项解析.md，并按现有项目接上列表/详情（如需要）。

对齐站内已有风格

先阅读本仓库已有 notes/ 下 1～2 篇范文，再按同样标题层级、代码块风格处理语雀《文档名》。

更新已上线笔记

语雀《文档名》已更新。请拉最新 markdown，覆盖本地对应 md，并标出 diff 要点。

7. 图片与附件

可对 Agent 说：

检查这篇 MD 里所有图片链接；不能公网访问的，请下载到 static/notes/<slug>/ 并改写路径。

8. 安全注意

1. 语雀 Token、服务器密码不要写进仓库，不要写进聊天记录长期保存。
2. 默认：Agent 先预览，老师确认后再写文件、再部署。
3. 含学生隐私、未公开成绩、内网地址/密码的文档，不要标「待发布」。
4. Token 泄露：立刻在语雀作废并重建，再重新 yuque-mcp install。

9. 常见问题

10. 最短口令（可贴显示器）

1. 语雀定稿，标「待发布」
2. Cursor 打开网站源码
3. Agent：语雀 MCP 拉稿 → 我确认
4. Agent：写入 notes/（必要时改列表/路由）
5. 提交并部署 → 打开 /note 验收
6. 语雀标「已发布」

11. 附录：语雀 MCP 常用能力（只读为主）

完整工具列表见：https://github.com/yuque/yuque-mcp-server

文档用途：发给老师照着做即可。若网站笔记目录名与本文 notes/ 不一致，把第 3、4、5 节路径改成你们仓库真实路径后继续用。