如何修改网站 Wiki
Vinci 机器人队网站的 Wiki 有三种编辑方式：CMS 富文本编辑、CMS 在线 Markdown 编辑，以及通过 GitHub Pull Request（下文简称 PR）提交修改。
如果只是修改少量文字，前两种方式更直接；如果需要新增章节、批量修改、使用本地编辑器或保留完整的代码审查记录，推荐使用第三种方式。
方式一：使用 CMS 富文本编辑器
打开 CMS 登录页，登录已通过审核的成员账号。
在“文章”中找到需要修改的 Wiki，创建编辑草稿；也可以在“草稿”页面新建文章草稿。
在编辑页选择“富文本”，像使用普通文档编辑器一样修改标题、段落、列表、图片和代码块。
保存前查看“发布效果”，确认排版正确。
富文本适合不熟悉 Markdown 的成员。如果页面含有 HTML、Vue/MDC 组件或其他扩展语法，编辑器可能显示兼容性警告；此时应使用 Markdown 源码模式并仔细核对预览。
方式二：在 CMS 中直接编辑 Markdown
按照方式一进入文章草稿。
选择“Markdown 源码与预览”。
在左侧直接修改 Markdown，在右侧对照网站最终的发布效果。
需要图片时，可使用草稿页面的图片上传功能，系统会上传图片并插入对应的 Markdown 链接。
这种方式无需在本地安装 Git，适合单篇文章的精确修改。
方式三：通过 GitHub PR 导入（推荐）
为什么推荐 PR
PR 不仅适合较大的 Wiki 修改，也是使用 Codex 等 AI Agent 协助维护教程时最方便的方式。飞书和网页富文本编辑器适合人工修改单篇内容，但 Agent 很难一次读取整套教程、跨文件搜索关联内容并批量修改。Markdown 是普通文本文件，Agent 可以直接读取、搜索、比较和修改，最后再通过 Git diff 和 PR 由人工审查。
因此，对于需要整体检查、批量改错、统一格式或修改多篇文章的任务，推荐使用 Markdown + GitHub PR：
可以在本地使用 VS Code 的搜索、预览、格式化和图片上传工具。
Codex 等 Agent 可以批量阅读相关 Markdown，理解章节之间的联系，再一次修改多个文件。
可以一次修改多篇文章，并在 GitHub 中清楚查看每一行差异。
修改人和审核人可以在 PR 中讨论，不会直接改动正式网站。
CMS 导入时会检查路径、Frontmatter、内容冲突和高风险语法。
Agent 完成修改不代表内容已经正确。提交 PR 前仍要由人检查文章原文、差异、图片、链接和 Frontmatter，不能让 Agent 自行 Merge 或发布。
第一步：准备内容仓库和分支
网站的 Markdown 位于 SDUTVINCI/sdutvinci_content 内容仓库。
编辑前先让内容仓库跟上数据库
建议在开始编辑前，先请管理员在 CMS 工作台找到“最近全量对账”卡片，点击“手动全量导出”，并等待页面显示成功。这一步会把 PostgreSQL 中的最新正式内容对账并导出到内容仓库，避免从过时的 Markdown 开始修改。普通成员看不到该按钮时，联系管理员执行即可。
全量导出成功后，再从 Clone 仓库开始。下面每一步只有一条命令，请按顺序执行，不要把几条命令粘成一行。
账号有内容仓库写入权限
在电脑上选一个用来存放仓库的文件夹，在该文件夹中打开终端。
从 GitHub Clone 内容仓库：
git clone https://github.com/SDUTVINCI/sdutvinci_content.git进入刚刚 Clone 下来的仓库：
cd sdutvinci_content切换到主分支：
git switch main拉取刚才全量导出后的最新内容：
git pull --ff-only origin main从最新
main创建自己的分支：git branch PR/XXX切换到刚创建的分支：
git switch PR/XXX查看当前分支：
git branch --show-current
把 XXX 替换为这次修改的简短名称。例如，先输入 git branch PR/wiki-guide 创建分支，再输入 git switch PR/wiki-guide 切换分支。第 8 步应显示 PR/wiki-guide，不能显示 main。
一台电脑只需要 Clone 一次。如果本地已经有 sdutvinci_content 仓库，不要在原目录里重复 Clone；进入已有仓库后，从上面的第 4 步开始即可。
重要警告：一定要从刚刚 Pull 的最新
main创建PR/XXX分支，并且只在PR/XXX上修改。绝对不要直接在main上编辑、Commit 或 Push。 开始修改前，先在终端或 VS Code 左下角再次确认当前分支名以PR/开头。
账号没有内容仓库写入权限
没有权限时不能把分支 Push 到官方仓库，需要先在 GitHub 上 Fork：
打开
SDUTVINCI/sdutvinci_content，点击Fork，把仓库 Fork 到自己的 GitHub 账号。Clone 自己的 Fork：
git clone https://github.com/你的GitHub用户名/sdutvinci_content.git进入仓库：
cd sdutvinci_content记录官方仓库地址：
git remote add upstream https://github.com/SDUTVINCI/sdutvinci_content.git切换到主分支：
git switch main从官方仓库拉取最新
main：git pull --ff-only upstream main从最新
main创建自己的分支：git branch PR/XXX切换到刚创建的分支：
git switch PR/XXX查看当前分支：
git branch --show-current
修改完成后，把 PR/XXX Push 到自己的 Fork（origin），再从 Fork 向 SDUTVINCI/sdutvinci_content 的 main 创建 PR。不熟悉分支、Push、Fork 或 PR 的成员，请先阅读 Vinci 机器人队 Git 实操教程 中的“使用 Pull Request”、“向没有写入权限的仓库提交 PR”和 VS Code 操作部分。
Git 实操教程介绍的是通用 PR 流程，其中包含普通代码项目的合并步骤。网站内容 PR 只参考创建分支、Fork、Commit、Push 和创建 PR 的部分，不要照着教程合并 PR。 不确定时请停止操作并联系管理员，不要随意点击 Merge、Close 或 Delete branch。
Wiki 的常见路径如下：
wiki/
└── 2025-07-01-Nuxt.js网站框架/
├── index.md
├── 0100-简介.md
├── 0200-部署方案.md
└── 0300-如何修改网站Wiki.md最外层 Wiki 目录使用
YYYY-MM-DD-专题名的格式。index.md是该专题的入口页。不要手工修改
.vinci/snapshot.json；它由网站内容导出流程维护。
章节文件名到底怎么排号
先记住两句话：
文件名前面的
0050、0100、0200只是用来排前后的标签，网页不会直接显示这些数字。前面有几段四位数字，就是第几级。
0100-标题.md是一级，0100-0100-标题.md是二级，0100-0100-0100-标题.md是三级。
再看一个完整例子：
文件名 网页显示
0050-准备.md 1
0100-入门.md 2
0100-0050-安装.md 2.1
0100-0100-使用.md 2.2
0100-0100-0100-配置.md 2.2.1为什么最后一篇显示为 2.2.1？
先看第一段：
0050排在0100前面，所以0100是第2章。再看第二段：第
2章下面，0050排在0100前面，所以0100是第2个小节。最后看第三段：
2.2下面只有这一篇，所以它是第1个小节。
合起来就是 2.2.1。如果把上面的 0050-准备.md 和 0100-0050-安装.md 都去掉，三个 0100 在各自那一级都排第一，那么 0100-0100-0100-配置.md 就会显示为 1.1.1。
实际命名时，先看同级已有文件，再把新文件放到想要的位置。新增到最后时通常继续用 0100、0200、0300……；想插到两篇中间时，可以用 0050、0150 这样的中间数，不用把后面的文件全部改名。
第二步：编辑 Markdown 和 Frontmatter
修改已有文章时，保留文件原有的 vinciId，不要删除、更换或复制给其他文章。
通过 PR 新增文章时，则不要手工填写 vinciId、publishedAt 和 updatedAt。CMS 导入和正式发布时会分别生成稳定 ID 和时间信息。新文章可以从下面的 Frontmatter 开始：
---
title: 文章标题
description: 用一句话介绍这篇文章
authors:
- zhangsan
---authors 使用成员的稳定拼音 ID，不要直接填中文姓名。网页会根据稳定 ID 显示成员中文姓名；如果不确定自己的 ID，可以在 CMS 的成员或文章署名信息中查询。
对文章做实质性补充但不是原作者时，可在 Frontmatter 中增加 contributors：
contributors:
- lisi提交前至少检查：
Markdown 预览是否正常，标题层级是否连续。
图片是否使用可访问的 CDN HTTPS 链接，且 alt 文本能说明图片内容。
文件是否仍位于正确的 Wiki 目录，有没有意外改动其他文章。
已有文章的
vinciId是否保持不变，新文章是否没有手工填写vinciId。
第三步：创建 GitHub PR
将分支 Push 到 GitHub。
创建一个目标为
SDUTVINCI/sdutvinci_content的main分支的 PR。在 PR 标题和说明中写清修改了哪些 Wiki、修改原因和需要重点检查的地方。
在
Files changed中查看完整差异，确认没有 Token、密码、本机绝对路径或无关文件。
创建 PR 后，GitHub 这一步就已经完成了。绝对不要在 PR 页面点击
Merge pull request、Squash and merge或Rebase and merge。下一步必须是打开 CMS 的“外部内容导入”，由 CMS 读取和导入 PR。
PR 是内容提案入口，不是网站的正式发布入口。即使 GitHub 显示绿色的可合并按钮，也不要手工合并。不会操作时，创建好 PR 后就停下，把 PR 链接交给有 CMS 权限的成员或管理员，不要随意修改 PR 的 Base、关闭 PR 或删除分支。
正式内容由 PostgreSQL 管理。管理员在 CMS 正式发布后，系统会再把正式版本导出回内容仓库，所以不需要、也不允许通过手工 Merge 让网站更新。
第四步：在 CMS 导入 PR
登录 CMS，打开“外部内容导入”。
输入 PR 链接或 PR 编号，让系统先执行 Dry Run 检查。
根据页面显示查看每一项的类型、风险、冲突和阻止原因。转移、删除、高风险语法和内容冲突需要额外确认或处理。
选择需要导入的可操作项目，再执行导入。
导入只会创建 PostgreSQL 草稿或提案，不会自动 Merge PR、通过审核或发布网站。页面显示“已创建草稿”后，还需要继续完成下一节的审核流程。
导入完成后，维护者可以把检查摘要留言到 PR。管理员确认所需项目均已安全导入后，可以关闭 PR；如果源分支位于官方内容仓库，还可以在 PR 关闭后单独确认删除源分支。
草稿导入后：提交审核和正式发布
无论使用上面哪种编辑方式，内容都不会在保存或 PR 导入后立刻出现在正式网站上。完整流程是：
创建或导入草稿
↓
编辑者检查预览并提交审核
↓
管理员审核（通过或驳回）
↓
管理员正式发布
↓
前台网站更新，正式 Markdown 随后导出到内容仓库进入 CMS 的“草稿”页，打开刚创建或导入的草稿。
检查标题、摘要、作者、协作者、Wiki 路径、正文和“发布效果”。
点击“提交审核”。审核完成前，提交人可以按页面提示撤回。
管理员在“审核”页查看变更内容和预览，选择审核通过或驳回。
审核通过不等于已经上线；管理员还需要对“待发布”文章执行“正式发布”。
如果审核驳回，编辑者应根据意见修改原草稿，再次检查预览并重新提交。只有“正式发布”成功后，这次 Wiki 修改才会成为网站的正式内容。
常见问题
PR 已经创建，为什么网站还没变？
PR 只是提案。请确认已在 CMS 中完成 PR 导入，导入的草稿已提交审核，且管理员已经审核通过并正式发布。
为什么某个文件被阻止导入？
先阅读页面显示的具体阻止原因。常见原因包括路径或 Frontmatter 无效、已有活动草稿、数据库正式版本与 PR Base 冲突，以及新增了 HTML、Vue/MDC 等高风险语法。不要通过删除 vinciId、强行覆盖或手工修改 snapshot 规避检查。
导入后还可以在 CMS 里继续修改吗？
可以。PR 导入后生成的是普通 CMS 草稿，可以继续使用富文本或 Markdown 源码模式修改。修改后仍需保存、核对发布效果并提交审核。