Repository navigation
本版本是 Azek创游世界文档 继 v0.6.0 - 文档站体验、UI 视觉与维护系统增强版 之后的一次系统升级。
v0.6.0 主要围绕文档站 UI 视觉、文档元信息、维护者信息、链接治理、性能优化、Issue 反馈模板、README 入口和长期维护流程进行增强。本版本在此基础上继续推进，把升级重点从“让文档站更完整、更好看”，进一步扩展到 清亮阅读体验、正式域名 SEO、搜索收录治理、知识库内容审计、无用文档审计、发布前最终巡检和 Cloudflare Pages 自动部署恢复。
本版本的核心目标是：
让 Azek创游世界文档 从“视觉增强型资料库”，进一步升级为“更清亮、更可检索、更可审计、更适合长期维护的创游世界中文知识库”。
版本定位
本次版本不是单纯的 UI 调整，也不是只修几个链接，而是一次偏工程化的资料库升级。
它主要解决这些问题：
- 首页品牌名和站点定位不够稳定。
- 文章页视觉效果较丰富，但长文阅读还可以更清亮、更克制。
- 正式域名、旧域名、默认 pages.dev 域名之间的搜索收录信号需要统一。
- robots、sitemap、canonical 等 SEO 基础信号需要更稳定的自动检查。
- 文档中存在 AI 整理后可能出现的强结论、语气过满、证据不足和术语前后不一致风险。
- 仓库需要一套更安全的无用文档、废弃文档、重复文档和孤儿文档审计流程。
- 发布前需要一套可重复执行的最终巡检流程，降低每次发布时漏检查的风险。
- Cloudflare Pages 自动部署需要重新确认并恢复到 GitHub
main分支自动构建模式。
本版本之后，Azek创游世界文档的长期方向更加明确：
- 资料可导航
- 结论可追溯
- 内容可检索
- 文档可审计
- 发布可复查
- 结构可长期维护
- 更适合玩家学习、资料整理和 AI / RAG 检索
本次重点更新
- 重构首页视觉体验，让首页更清亮、更专业、更像长期维护型文档站入口。
- 修复首页
Azek创游世界文档标题换行问题，避免品牌名被拆成不自然的上下两行。 - 新增首页专用样式层
cysj-home.css，让首页样式和文章阅读样式分离。 - 新增清亮阅读主题覆盖层，优化文章页标题、正文、列表、表格、代码块、引用块、目录、侧边栏和移动端体验。
- 收敛顶部导航结构，将主入口整理为首页、开始阅读、专题资料、维护和关于。
- 将右侧目录层级从 h2-h4 收敛为 h2-h3，减少长文页面目录过深、过密的问题。
- 统一站点公开名称为
Azek创游世界文档。 - 统一正式域名为
https://cysjdocs.azek431.top/。 - 修复 robots.txt、sitemap、canonical、站点标题、站点描述和搜索收录基础信号。
- 新增搜索收录检查脚本，支持源码层和构建产物层双重检查。
- 修复旧域名检查误报，避免检测脚本中的旧域名数组被误判为真实旧域名污染。
- 新增知识库内容审计流程，用于检查强结论、证据不足、AI 味、长句、长段落和潜在事实不一致问题。
- 新增文档语法与真实性审计报告，帮助后续逐篇校对资料准确性。
- 新增无用与废弃文档清理审计流程，用于扫描空壳文件、临时文件、备份文件、重复文档、废弃文档和孤儿文档。
- 更新发布前最终巡检报告，确认构建、sitemap、robots、SEO 检查和线上访问均正常。
- 恢复 Cloudflare Pages 通过 GitHub
main分支自动构建部署。
一、首页与品牌体验升级
本版本对首页进行了比较明显的视觉重构，重点解决首页品牌展示、入口层级和用户第一眼理解成本的问题。
1. 统一首页品牌标题
此前首页标题在部分屏幕宽度下容易把 Azek 和 创游世界文档 拆成两行，视觉上不够自然，也不利于形成稳定的站点品牌。
本版本统一首页主标题为：
Azek创游世界文档
同时通过首页专用样式控制标题字号、宽度、换行和移动端表现，让品牌名在桌面端和手机端都更稳定。
2. 重写首页 Hero 文案
首页 Hero 文案重新整理为更明确的知识库定位：
创游世界脚本、组件、UI 与项目设计知识库
首页说明也从普通介绍改为更具体的资料范围说明，突出以下内容：
- 创游世界脚本教程
- 组件机制
- 变量与广播
- UI 交互
- 项目设计
- 官方教程 OCR
- 引擎更新
- 新手入门路线
- 长期维护规范
这样用户进入首页后，可以更快理解这个站点不是普通博客，而是一个围绕创游世界资料整理、学习和长期维护的知识库。
3. 收敛首页操作按钮
首页操作按钮重新整理为三个核心入口：
- 开始阅读：进入知识库总导航。
- 新手路线：帮助第一次访问的用户快速找到学习顺序。
- GitHub：方便查看仓库、反馈问题和参与维护。
这样首页入口更聚焦，不会让新用户一进来就被大量导航项打散注意力。
4. 重构首页功能卡片
首页功能卡片重新整理为六个核心方向：
- 新手阅读路线
- 脚本与组件系统
- UI 与交互设计
- 项目设计实战
- OCR 与证据资料
- 长期维护规范
这些卡片对应当前资料库的主要内容结构，让首页从“展示页面”进一步变成真正的“知识库导航入口”。
5. 新增首页专用样式
本版本新增首页专用样式层：
docs/.vitepress/theme/styles/cysj-home.css
首页相关的标题、Hero、按钮、卡片、背景氛围和移动端适配不再继续混入通用主题样式中。
这样后续继续优化首页时，不容易误伤文章页阅读体验，也让主题维护边界更清晰。
二、清亮阅读主题升级
本版本继续优化文章页阅读体验，方向不是继续叠加强烈视觉效果，而是让文档更清晰、更克制、更耐读。
1. 文章标题更克制
本版本收敛了文章标题大小和标题间距，减少标题过大带来的压迫感。
优化方向包括：
- h1 更克制，减少首屏占用。
- h2 / h3 层级更清楚，适合长文扫描。
- h4 不再过度干扰目录结构。
- 标题上下间距更适合资料型文章。
- 文章页更强调正文阅读，而不是做成展示型页面。
本版本的阅读方向是：
首页可以有品牌感，文章页优先保证清晰、克制、耐读。
2. 正文阅读体验优化
本版本优化了正文行高、段落间距、列表间距、链接样式和强调文本，让脚本教程、项目设计、OCR 说明、维护报告等不同类型文章都更好读。
优化范围包括：
- 正文段落
- 有序列表
- 无序列表
- 站内链接
- 加粗文本
- 行内代码
- 代码块
- 表格
- 引用块
- 自定义提示块
- 图片展示
3. 表格与代码块优化
创游世界资料库中有大量机制说明、变量说明、证据等级、路线表和维护报告。本版本继续优化表格边框、背景、间距和横向滚动体验，减少移动端表格溢出问题。
代码块和行内代码也继续保持清晰、克制，方便展示命令、路径、配置项和脚本片段。
4. 侧边栏与右侧目录优化
本版本重新收敛导航层级：
- 顶部导航减少过多顶层入口。
- 右侧目录层级收敛到 h2-h3。
- 侧边栏继续保持自动生成。
- 文档底部上一页 / 下一页区域继续保持清晰。
- 移动端阅读布局继续优化。
这让长文页面的导航压力更小，也更适合普通用户按专题阅读。
三、导航结构整理
本版本对顶部导航进行了重新整理。
导航主入口收敛为：
- 首页
- 开始阅读
- 专题资料
- 维护
- 关于
其中“开始阅读”聚合新手阅读路线、快速入门索引、按问题查资料和知识库总导航；“专题资料”聚合脚本系统、项目设计、核心研究、教程资料、OCR 资料和引擎更新；“维护”聚合维护报告、证据规则和内容质量审计相关页面。
这样做的好处是：
- 顶部导航更短。
- 移动端更不容易拥挤。
- 新用户更容易从“开始阅读”进入。
- 老用户可以从“专题资料”直接进入对应方向。
- 维护类内容不再和资料类内容混在一起。
四、正式域名与搜索收录治理
本版本重点修复搜索引擎仍然偏向旧域名、文章页面不容易被发现、不同入口信号不统一的问题。
1. 站点名称统一
本版本将站点公开名称统一为：
Azek创游世界文档
统一范围包括：
- VitePress title
- titleTemplate
- themeConfig.siteTitle
- 首页 frontmatter
- 站点 description
- OG title
- OG description
- Twitter title
- Twitter description
- README 公开说明
- llms.txt 说明
- 站点首页文案
这样可以减少不同页面、不同平台、不同搜索入口显示名称不一致的问题。
2. 正式域名统一
本版本将正式域名统一为：
https://cysjdocs.azek431.top/
并围绕这个域名修复搜索收录信号：
- sitemap hostname 指向正式域名。
- robots.txt 指向正式 sitemap。
- 页面 canonical 指向正式域名。
- OG url 指向正式域名。
- README 入口指向正式文档站。
- 检查脚本检测旧域名残留。
3. canonical 自动生成
本版本在 VitePress 页面数据处理中为页面生成 canonical，避免同一篇文章因为旧域名、默认 pages.dev 域名或不同访问路径造成搜索引擎重复判断。
这对资料库很重要，因为文档站页面数量较多，如果多个域名同时暴露同一份内容，搜索引擎容易把权重分散到旧地址或默认地址。
4. robots 与 sitemap
本版本继续保持 robots.txt 指向正式 sitemap：
User-agent: *
Allow: /
Sitemap: https://cysjdocs.azek431.top/sitemap.xml
本次最终巡检确认构建后的 sitemap 覆盖：
210 个页面
并且线上访问正常：
https://cysjdocs.azek431.top/ 200 OK
https://cysjdocs.azek431.top/sitemap.xml 200 OK
https://cysjdocs.azek431.top/robots.txt 200 OK
五、搜索收录检查脚本
本版本新增搜索收录检查流程，把 SEO 从“手动看配置”升级为“源码层 + 构建产物层双检查”。
1. 源码层检查
新增命令：
pnpm run docs:search-index:check
用于检查源码中的搜索收录基础信号，包括：
- 站点标题是否使用正式名称。
- titleTemplate 是否正确。
- siteTitle 是否正确。
- sitemap hostname 是否指向正式域名。
- robots.txt 是否指向正式 sitemap。
- 是否存在旧域名残留。
- 是否存在不该出现的 noindex。
- Markdown 页面数量是否正常。
- canonical 生成逻辑是否存在。
2. 构建产物层检查
新增命令：
pnpm run docs:search-index:dist
用于检查构建后的真实产物，包括：
sitemap.xml是否存在。robots.txt是否存在。- 首页 HTML 是否存在。
- sitemap URL 数量是否正常。
- 页面 HTML 是否生成 canonical。
- 构建产物是否残留旧域名。
- 构建产物是否出现异常 noindex。
这一步非常重要，因为源码看起来正确，不代表最终构建出来的 HTML、robots 和 sitemap 一定正确。
3. 旧域名误报修复
本版本修复了旧域名检查脚本对 scripts/check-search-indexing.mjs 的误报。
搜索收录检查脚本需要保留旧域名列表，用来检测源码和构建产物里是否还有旧域名残留；但域名检查脚本不应该把这组“用于检测的旧域名数组”当成真实污染。
本版本将搜索收录检查脚本加入旧域名允许列表，保留检测能力，同时避免 docs:domain:check 误报。
六、知识库内容审计与资料校对规则
本版本新增知识库内容深度审计和资料校对规则，核心目标是避免资料型文档出现三个问题：
- 把推测写成确定结论。
- 把经验总结写成官方机制。
- 把 AI 整理出的顺口表达当成真实资料。
1. 资料事实、经验总结和推理模型分层
本版本继续强调资料库内容应该分成三类：
资料事实：
来自截图、OCR、官方教程、引擎更新、界面内容或明确实测记录。
经验总结：
来自整理者使用经验、项目维护经验或多个资料之间的归纳。
推理模型：
为了帮助理解而做的解释、类比、结构化总结或学习路径设计。
这样做的目的不是让文档更复杂，而是避免“看起来很像事实”的内容误导读者。
2. 证据等级思路延续
本项目继续使用证据等级思路：
E1 原始证据
E2 整理证据
E3 研究结论
E4 待验证内容
本版本新增的审计脚本也围绕这个方向继续补强，帮助后续逐步把重点文档补上来源、证据、状态和待验证标记。
3. 强结论审计
本版本特别关注这类词：
必须、一定、只能、不能、无法、官方、支持、不支持、会自动、不会、唯一、最佳、最强
这些词在教程文档里很容易让读者误以为结论已经完全验证。审计脚本会扫描这些强结论，并检查附近是否有 OCR、截图、官方教程、引擎更新、实测、待验证等证据提示。
七、文档语法与真实性审计
本版本新增：
pnpm run docs:truth:audit
用于扫描全站 Markdown 文档中的语法、表达、结构和真实性风险。
1. 检查范围
该脚本会检查：
- frontmatter 是否缺失关键字段。
- 标题层级是否跳跃。
- 是否存在空链接。
- 图片是否缺少 alt。
- 是否存在疑似伪表格。
- 代码块围栏是否闭合。
- 是否出现重复词和重复标点。
- 中文正文中是否混用英文标点。
- 是否存在过长句子和过长段落。
- 标题或正文是否有明显 AI 味或营销化表达。
- 强结论附近是否缺少证据提示。
- 提到官方教程、引擎更新、版本号时是否缺少来源提示。
- 同一术语是否同时出现“支持 / 不支持”“可以 / 不能”等潜在正反描述。
2. 本次最终审计结果
本次发布前运行结果显示：
checked 197 markdown file(s)
found 987 issue(s)
possible contradiction terms: 21
这些结果不代表有 987 个事实错误，而是说明当前资料库中仍有大量内容值得后续人工复核，包括：
- 表达过强
- 证据提示不足
- 句子过长
- 标题偏 AI 味
- 部分术语可能前后描述不一致
- 部分报告内容可能被链接检查误识别
本版本不会自动改写这些事实类内容，而是先生成报告，作为后续逐篇校对的路线图。
3. 为什么不自动批量改事实
资料型知识库最怕“把错误改得更自然”。
所以本版本的真实性审计只做定位，不自动改写结论。
后续处理原则是：
先找问题
再找来源
再降语气
再补证据
最后才改正文
八、无用与废弃文档清理审计
本版本新增：
pnpm run docs:prune:audit
用于扫描文档站中疑似无用、废弃、临时、重复、空壳和孤儿 Markdown 文件。
1. 清理策略
本版本采用安全清理策略：
- 只把高置信废弃文件列为可删除对象。
- 对普通孤儿文档只列入人工复核，不默认删除。
- 自动保护首页、关于页、总导航、维护导航等关键入口。
- 自动保护 OCR、证据、官方、原始资料相关内容。
- 对仍被引用的废弃文档不自动删除，避免导航或链接断裂。
- 生成 Markdown 报告和 JSON 清单，方便检查与回滚。
2. 本次最终审计结果
本次发布前运行结果显示：
scanned markdown files: 210
candidates: 6
high-confidence deletable: 0
这说明当前仓库没有明显可以直接删除的高置信废弃文档。少量候选项需要人工复核，但不应该在发行版前激进删除。
这也是本版本比较重要的结论：
当前资料库虽然仍有内容质量和链接 WARN，但没有发现适合直接批量删除的高风险废弃文件。
九、自动化维护流程增强
本版本继续加强自动化维护能力，让资料库更适合长期维护，而不是每次靠人工翻文件。
1. 当前关键维护命令
本版本重点确认和使用的命令包括：
pnpm run quality:check
pnpm run docs:check:light
pnpm run docs:search-index:check
pnpm run docs:search-index:dist
pnpm run docs:truth:audit
pnpm run docs:prune:audit
pnpm run docs:build
这些命令覆盖：
- UI 关键文件检查
- 正式域名检查
- CSS 健康检查
- 轻量链接检查
- 仓库健康巡检
- 搜索收录源码检查
- 搜索收录构建产物检查
- 文档语法与真实性审计
- 无用与废弃文档审计
- VitePress 正式构建
2. 发布前最终巡检
本版本发布前已完成最终巡检：
quality:check 通过
docs:check:light 通过
docs:search-index:check 通过
docs:build 构建成功
docs:search-index:dist 通过
docs:truth:audit 已生成报告
docs:prune:audit 已生成报告
git diff --check 无格式错误
构建结果显示：
Sitemap URL count: 210
Dist SEO check scanned 210 html file(s)
Search indexing check passed (dist)
线上检查结果显示：
https://cysjdocs.azek431.top/ 200 OK
https://cysjdocs.azek431.top/sitemap.xml 200 OK
https://cysjdocs.azek431.top/robots.txt 200 OK
这说明本版本已经完成发布前基础验证。
十、Cloudflare Pages 自动部署恢复
本版本重新确认并恢复 Cloudflare Pages 通过 GitHub main 分支自动构建部署。
当前推荐配置为：
Production branch:
main
Build command:
pnpm run docs:build
Build output directory:
docs/.vitepress/dist
这次也修正了部署配置中容易出错的一点：
- VitePress 站点目录在
docs/ - 构建命令是
pnpm run docs:build - 最终输出目录不是
.vitepress/dist - 正确输出目录应该是
docs/.vitepress/dist
后续发布流程恢复为：
本地修改
→ VS Code 提交
→ Push 到 GitHub
→ Cloudflare Pages 自动构建
→ cysjdocs.azek431.top 自动更新
十一、README 与项目入口同步
本版本继续保持 README 作为项目入口的定位。
README 当前强调：
- 在线文档站优先访问。
- GitHub 仓库用于查看源码、反馈问题和参与维护。
- Gitee 作为镜像入口。
- 资料库覆盖脚本、组件、变量广播、UI、项目设计、OCR、官方教程、引擎更新和维护报告。
- 项目目标是可导航、可追溯、可检索、可维护，并适合 AI 检索。
- 维护原则强调不随意删除原始资料、不把待验证内容写死、重要结论尽量有关联来源。
本版本新增的 SEO、真实性审计、废弃文档审计和最终巡检，都是围绕这些 README 维护原则继续补强。
十二、本版本对用户的实际影响
1. 对普通读者
- 首页更清楚，进入资料库后更容易知道从哪里开始。
- 新手可以更快进入阅读路线。
- 想查脚本、UI、组件、项目设计、OCR 资料的用户更容易找到入口。
- 文章页阅读压力降低，标题、正文、表格和目录更清晰。
2. 对资料查找者
- 正式域名、sitemap、robots、canonical 信号更统一。
- 后续搜索引擎更容易重新发现正式域名页面。
- 资料分类、导航入口和自动目录继续保持更新。
- OCR 与证据资料入口更明确。
3. 对维护者
- 发布前检查流程更完整。
- 搜索收录不再只靠手动观察。
- 内容真实性风险可以通过报告逐步处理。
- 废弃文档不会被粗暴删除，而是先审计、再确认、再清理。
- 未来大规模整理文档时更安全。
4. 对 AI / RAG 使用者
- 站点标题、description、导航、证据等级和
llms.txt更统一。 - sitemap 覆盖范围更清楚。
- 低价值页面和维护报告后续可以逐步排除或标记。
- 强结论、待验证内容和事实来源会逐步更清晰。
十三、已知问题与后续优化方向
本版本仍保留一些后续优化项。它们不阻塞本次发布，但会作为后续版本继续处理。
1. CSS 与前端性能
cysj-ultimate.css中仍有较多!important。- 主题 CSS 总体体积继续增大。
- VitePress 构建仍提示部分 chunk 超过 500KB。
- 后续需要继续收敛旧主题 CSS、减少重复覆盖，并考虑更细的构建体积优化。
2. 链接与历史内容
- 轻量链接检查仍有历史链接 WARN。
- 部分 WARN 来自审计报告、自动目录或历史文档里的文本识别。
- 后续需要按专题逐步修复真实失效链接，并减少报告类页面对链接检查的干扰。
3. 内容真实性审计
docs:truth:audit仍发现大量待人工复核项。- 这些项不等于全部错误，但说明资料库仍需要逐步校对语气、证据和术语一致性。
- 后续应优先处理 ERROR、强结论缺证据、官方说法缺来源和潜在正反描述冲突。
4. 搜索收录
- 本版本已经修复源码和构建产物层面的搜索收录基础信号。
- 搜索引擎重新抓取和更新结果仍需要时间。
pages.dev默认域名建议继续通过 Cloudflare Redirect Rules / Bulk Redirects 跳转到正式域名，避免重复站点被收录。
十四、后续计划
后续版本建议继续围绕以下方向推进：
- 分批修复轻量链接检查中的历史 WARN。
- 逐篇处理文档语法与真实性审计报告中的高优先级问题。
- 给重点文档补充 source、evidence、confidence、status 等字段。
- 继续区分资料事实、经验总结和推理模型。
- 收敛旧主题 CSS，减少重复覆盖和
!important。 - 优化构建体积、搜索索引大小和首页加载体验。
- 继续完善 OCR 原始资料、截图编号、证据链和待验证清单。
- 继续补充脚本系统、变量、广播、UI、组件、项目设计等核心专题。
- 完善 Cloudflare Pages 默认域名跳转，减少重复域名收录风险。
- 优化 README 中的伪表格显示，让 GitHub 仓库首页阅读更规整。
总结
v0.7.0 不是一次简单的样式更新，而是 Azek创游世界文档 从“视觉增强型文档站”向“可检索、可审计、可长期维护的知识库系统”迈出的一步。
本版本完成了首页清亮化、文章阅读优化、正式域名 SEO、搜索收录检查、知识库真实性审计、废弃文档审计和发布前最终巡检，为后续继续扩充资料、校对事实、优化搜索和增强 AI 检索体验打下了更稳的基础。