A80s 博客维护说明

项目信息

• GitHub 仓库：https://github.com/vince6799/Blog
• 公开站点：https://blog.a80s.com
• 默认分支：main
• 正式文章目录：_posts/
• 草稿目录：_drafts/
• 本地预览目录：outputs/
• 本地预览脚本：scripts/render-local-preview.rb

工作范围

• 在当前仓库中维护 A80s 程序员手记，包括文章、首页、关于页面、RSS、SEO、分享功能和搜索引擎相关配置。
• 先检查当前文件和 Git 状态，保留用户已有修改，不处理与当前任务无关的文件。
• 动态状态以仓库和 GitHub 为准，不在本文件记录最近提交、Actions 运行编号或临时工作进度。

写作要求

• 技术内容优先核对官方文档、官方仓库、规范、源码和项目维护者发布的一手资料。
• 对快速演进的项目注明核对日期、版本或代码基线，并明确区分稳定能力、实验功能和未来设想。
• 不虚构作者亲历、测试数据、生产事故或使用效果。需要工程案例时，使用可核验的 issue、测试、postmortem 或源码事实，并说明来源。
• 先把概念边界、运行过程和工程限制讲清楚，再考虑比喻、观点和选型建议。
• 避免模板化排比、机械对仗、过度总结、空泛转折和明显的 AI 腔。
• 不刻意冒充个人经历；作者口吻应来自明确判断、技术取舍和可核验细节。
• 外部资料以摘要和分析为主，避免大段引用受版权保护的原文。
• 长文章应提供清晰目录；复杂流程可以使用 HTML/CSS 图、时序图、流程图或标明性质的终端示意。

文章与预览

• 新文章先保存在 _drafts/，Front Matter 设置 published: false。
• 用户确认发布前，使用 scripts/render-local-preview.rb 生成 outputs/ 下的本地 HTML 预览。
• 本地预览文件只用于审阅，不作为正式站点文件发布。
• 发布时将确认后的文章放入 _posts/，移除 published: false，并保留稳定的 permalink。
• 外部链接使用 target="_blank" 和 rel="noopener noreferrer"；站内链接保持当前窗口打开。
• 代码、表格、流程图和移动端布局需要具有可读样式，不能与正文混在一起。

本地脚本

• scripts/render-local-preview.rb 用于把一篇带 Jekyll Front Matter 的草稿或文章渲染成独立 HTML，供发布前在本地浏览器审阅。
• 脚本读取文章的 title、description、category 和 reading_time，并嵌入 _includes/styles.css、_includes/sections.css 与 _includes/about.css 中的站点样式。

• 调用格式为 ruby scripts/render-local-preview.rb SOURCE OUTPUT。例如：

  ruby scripts/render-local-preview.rb \
    _drafts/2026-08-17-example.html \
    outputs/example-preview.html
  

• SOURCE 是带 Front Matter 的文章文件，OUTPUT 是要生成的 HTML 文件；输出目录需要事先存在。
• 本地预览不执行完整的 GitHub Pages/Jekyll 构建，只用于检查正文结构和视觉效果。最终结果仍以 GitHub Pages 构建后的公开页面为准。
• scripts/ 属于需要版本管理的项目工具；outputs/ 属于可重新生成的产物，不应提交。
• 增加或修改脚本时，同时更新 scripts/README.md，并至少运行一次示例命令验证产物。

发布规则

• 只有用户明确要求“发布”时才执行远端写入。
• 发布优先使用已连接的 GitHub App；不要因为发布请求自动改用个人访问令牌。
• 普通文章发布只写入 _posts/。不要上传 _drafts/ 和 outputs/；只有脚本本身发生了有意修改时，才提交 scripts/ 中对应的文件。
• 发布前确认远端目标文件是否已存在，避免误覆盖同名文章。
• 发布后检查 GitHub Pages 构建状态；构建成功后访问公开文章地址，核对标题、正文、canonical、Open Graph 和页面样式。
• GitHub App 直接产生远端提交后，将本地 main 以 fast-forward 方式同步到 origin/main，不得强制推送或覆盖用户修改。
• 百度 URL 提交保持由既有定时工作流执行，不因普通文章发布额外触发即时提交。

站点约定

• 自定义域名已经启用，所有公开链接使用 https://blog.a80s.com，不要再使用 /Blog 项目路径。
• Cloudflare 负责 DNS 和站点前置服务；调整缓存、SSL 或安全规则前先检查现有配置和影响范围。
• RSS 地址为 /feed.xml，Sitemap 为 /sitemap.xml。
• 百度验证文件不应出现在 Sitemap 中。
• Google Analytics 测量 ID、搜索引擎 Token 和其他凭据不得重复硬编码到文章或说明文件中；沿用站点现有配置和 Repository secrets。
• BoostNet 文章中的推广链接使用 https://999.boostnet1.com/register?code=qo9BWfBU，不得替换成普通注册链接。

安全与 Git

• 不得把 Token、Repository secrets、Cookie、私钥或其他凭据写入仓库和输出文件。
• 不使用 git reset --hard、强制推送或其他破坏性命令，除非用户明确授权。
• 工作区包含无关或未跟踪文件时，只暂存和提交当前任务明确涉及的路径。
• 发布完成后报告文章地址、提交 SHA、Pages 构建结果以及是否已同步本地仓库。