博客仓库 Agent 工作指南

本文件适用于本仓库全部目录。用户当前明确要求优先；进入子目录时，同时检查更具体的 AGENTS.md。

项目定位与事实来源

• 这是 shensunbo.github.io 个人博客，基于 Hux Blog 模板，使用 Jekyll 4、kramdown/GFM 和 Rouge。
• 默认使用中文撰写和沟通，保留技术名词、命令、API 名称的准确写法。
• 内容包括 C++、渲染、图形学、Linux、Android、开发工具、问题排查及个人笔记。
• 先阅读目标文件、近期同类文章以及涉及的配置，再修改；不要用上游模板默认值替换本站约定。
• 以当前 _config.yml、Gemfile、package.json、Gruntfile.js 和模板实现为准。_doc/README.zh.md 含旧版主题说明，不能直接作为当前构建命令依据。
• .github/copilot-instructions.md 可作补充参考；示例标签、历史说明与实际配置不一致时，优先实际文件和本文约定。

目录与写入位置

• 用户指定文件或目录时，严格使用该位置；“写博客”不表示可以自行推送 Git 或部署。
• 未明确正式文章还是草稿时，优先在 _q_draft_post/ 完成可审阅内容，并说明位置。不要因为路径选择阻塞写作。
• 修改已有文章时保留其文件名、日期、作者及自定义 Front Matter，除非任务要求调整。
• 草稿转为正式文章时检查同名文件，避免覆盖已有内容或产生重复文章。
• 新文章文件名使用 YYYY-MM-DD-lowercase-hyphen-slug.md；用户指定名称时照用。不要批量重命名历史文件。
• 日期采用用户指定日期；未指定时使用当前 Asia/Shanghai 日期。

文章格式

新文章默认使用以下 Front Matter，并按主题选择已有标签：

1
2
3
4
5
6
7
8
9
---
layout:       post
title:        "具体、准确的文章标题"
author:       "shensunbo"
header-style: text
catalog:      true
tags:
    - tools
---

• 标签优先复用 README.md 中的分类：graphics、cpp、linux、android、tools、testing、english、reading、life。
• 避免为同一概念随意新增大小写或语言变体，如同时引入 C++ 与 cpp。已有文章的标签只在任务需要时整理。
• 只有需要封面时才添加 header-style: image 和存在的 header-img。
• 数学公式按需要设置 mathjax: true，遵守当前模板的支持方式。
• wip: true 会显示进行中标记，不是“不发布”开关。当前配置为 future: true，未来日期也不能用来隐藏文章。
• 不依赖尚未验证的 Mermaid 渲染支持。简单结构可用文本图或表格；确需图形时提供能在本站显示的图片，或在明确授权的功能范围内增加渲染支持。
• Front Matter 已展示文章标题，正文通常从引言及二级标题开始，避免重复堆叠同名一级标题。
• 代码块标明语言；表格、列表和标题前后保留空行。保持 UTF-8，新增文件不添加 BOM。
• 涉及 Liquid 示例时，按需要使用 raw/endraw 标签保护，避免 Jekyll 将示例当成模板执行。

技术文章的内容要求

• 开头说明具体问题、适用环境和读者能获得的结果。使用明确动词，避免宣传性或空泛表述。
• 从真实操作、日志、代码或用户提供的证据出发；不编造测试、版本、故障原因、性能数据及用户反馈。
• 区分“已观察事实”“由证据支持的判断”和“尚待验证的推测”。恢复手段有效，不等于已经证明代码级根因。
• 故障排查文章按实际需要覆盖：现象、环境、关键证据、对照实验、解决步骤、复测结果、结论边界和回退方法。
• 只写对理解结果有帮助的失败尝试，不照抄整段聊天或所有工具调用。
• 验证范围要准确。例如只复测 Chrome 成功，就不能写飞书和 ChatGPT 也已恢复。
• 区分实际执行过的步骤和提供给读者的参考步骤。命令返回码与实际状态不一致时，写明最终如何确认状态。
• 给出命令的运行位置和必要前提；不要在文章任务中实际执行具有修改、退出、删除、上传或重启作用的示例命令。
• 配置变更说明影响范围；可能覆盖已有配置的命令提供保留原值、备份或回退方式。
• 可复用示例使用清楚的占位符、相对路径或用户目录表达式。实际案例路径只有在帮助定位问题时才保留。
• 面向公开站点，避免发布凭据、内部地址、客户数据、聊天内容及无关个人文件路径。截图只保留与问题相关的区域。
• 引用外部结论时优先官方文档、源码或上游问题记录，链接到支持该结论的具体页面；不要把现象相似的问题单当作本机根因证明。

图片与链接

• 图片必须保存到仓库内可发布的位置，使用站点路径，例如 /img/in-post/example/diagram.png。
• 不把 /tmp/、工作机绝对路径或仅当前聊天可访问的附件地址写成公开文章的图片链接。
• 本地 Markdown 文件链接与网站 URL 用途不同；博客正文要使用读者在网站上可访问的链接。
• 不把诊断时的完整日志直接作为插图或附件发布；提取与论点相关的片段。

主题与资源维护

• 普通文章修改保持在内容与必要图片范围内。
• 修改主题样式时编辑 less/ 源码；修改主题脚本时编辑 js/hux-blog.js。由构建流程更新对应生成资源，不只手改压缩文件。
• _layouts/ 和 _includes/ 的改动可能影响全部页面，完成后检查文章页、首页和移动端布局。
• 未经任务要求，不调整 CNAME、站点 URL、作者信息、评论、统计标识、导航或部署方式。
• 不将仓库外其他工程的 HMI C++ 编码规则套用到博客文字或代码示例。代码示例应服务文章主题，并注明实际适用的标准版本。

构建与验证

命令从仓库根目录运行。先确认所需工具和依赖存在：

1
bundle check

按变更范围选择验证：

1
2
3
4
5
6
7
8
# 构建 Jekyll 站点
bundle exec jekyll build

# 本地预览；package.json 中 npm start 对应此命令
bundle exec jekyll serve

# 仅在修改主题 LESS/JS 时，使用已安装的本地 Grunt
./node_modules/.bin/grunt

• 普通文章首先检查 Front Matter、代码块、图片路径、链接和事实表述；依赖可用时执行 Jekyll 构建。
• 本地依赖未安装时说明缺少的工具或依赖。不要把语法检查描述成站点构建成功，也不要为了单篇文章自行升级依赖。
• bundle install、npm install 用于需要依赖准备的任务；避免无关的锁文件和版本变更。
• npm run dev 会同时运行 Grunt watch 与 Jekyll 预览，需要持续预览时再使用。
• Rakefile 中的 post 任务仍带上游作者 Hux 等旧默认值，preview 任务也使用旧命令；不要直接用它们生成本站文章或作为当前验证依据。
• 不提交 _site/、.jekyll-cache/、node_modules/ 或临时诊断输出。注意 .gitignore 还忽略 *.sh、*.log、*.lock 和 *.pdf；新增这类附件时检查是否真的被 Git 跟踪，不擅自强制添加。
• 文档或规则文件本身的简单修改不需要启动完整站点；检查格式、引用的路径和命令是否与当前仓库相符即可。

Git 与交付

• 开始前查看 git status --short，保留用户已有修改；不要顺手清理或回退无关内容。
• 生成或更新文件后，检查实际写入内容和本次差异，再说明结果。
• npm run push 会执行 git push origin master --tag，npm run boil 会推送另一远端分支；它们不是构建或测试命令。
• 只有用户授权提交、推送或部署时才执行对应操作。写入 _posts/ 表示准备正式文章源文件，不表示已在线发布。
• 交付时给出文件路径，简述内容和验证结果；如未执行构建或还有未证实的结论，明确说明，不夸大完成范围。