docs(blog): 更新 Jekyll 博客项目约束文档

- 修正文件标题为「项目约束」以强调规范性质
- 补充博客项目特有的写作加工和文件格式要求
- 明确项目事实，包括技术栈、存储路径和部署流程
- 细化写作目标，聚焦经验加工和读者理解导向
- 详细描述内容加工原则与方法，突出案例与判断
- 定义写作风格、语气、标点、留白及术语规范
- 规范文章结构与创建流程，提升文档一致性
- 补充构建流程说明和技术内容边界的具体要求
- 明确 Front Matter 和文件命名规范及内容边界
- 约束修改范围，区分文章与站点功能改动边界
- 提供完整的验证步骤及可能的环境问题应对方案

Author: Donglu

GEMINI.md

@@ -1,138 +1,151 @@
-# Jekyll Blog Project Context
-
-## 1. 项目概览 (Project Overview)
-这是 Donglu (DL) 的个人技术博客。基于 [Jekyll](https://jekyllrb.com/) (Ruby 静态网站生成器) 构建，使用默认的 `minima` 主题，通过 Markdown 文件生成静态页面。
-
-- **主要语言:** Ruby, Markdown, HTML, YAML
-- **框架版本:** Jekyll ~> 4.4.1
-- **使用主题:** minima
-- **使用插件:** jekyll-feed, nokogiri, mermaid_processor.rb (自定义插件)
-
-## 2. 核心行为准则 (Core Directives)
-
-### 2.1 写作风格
-- **硬核技术风**：行文简洁客观。避免夸张营销用语和过多 emoji，保持清晰干练的技术叙述。
-- **逻辑严密**：文章结构必须具备强逻辑性。通常遵循「问题现象 → 根本原因 → 解决方案 → 原理扩展/总结」的金字塔结构，层层递进。
-- **精炼准确**：结论要一针见血，避免啰嗦和无关紧要的发散。如果问题出在特定场景/特定前置条件，必须在开篇明确指出，不泛泛而谈。
-- **写作目标优先级**：准确先于修辞，清晰先于热闹，可扫读先于堆砌解释。
-
-### 2.2 语气规范
-- 使用克制、直接、可执行的中文；以说明、界定、引导为主，不用夸张宣传语。
-- 不使用第二人称（`你`、`您`、`同学`），如无必要不直接点名读者，用无主句或说明句即可。
-- 避免问候式开场（`Hello`、`Hi`）和口号式抽象表达。
-- **禁用黑话词**（除非该词在当前语境中有严格业务定义）：`赋能`、`抓手`、`闭环`、`沉淀`、`对齐`、`对标`、`拉通`、`打通`、`协同`、`联动`、`洞察`、`赛道`、`心智`、`调性`、`战役`、`链路`、`势能`、`兜底`。
-  - 优先替换为更具体表达：`赋能` → `提供`，`抓手` → `关键措施`，`闭环` → `完整流程`，`对齐` → `统一`，`兜底` → `保障机制`。
-
-### 2.3 标点规范
-- 中文引号统一使用直角引号：`「」`，不使用中文双引号 `""`。
-- 正文中避免连续使用多个感叹号、省略号、宣传口号式断句；避免使用感叹号。
-
-### 2.4 中英文留白
-在可见正文中，中文与半角英文单词、英文缩写、独立数字和版本号之间保留空格，提高可读性。
-
-- 正确：`获取批量 ID`、`HTTP 请求`、`版本 2.0`、`AI 服务`
-- **不要**对以下内容机械加空格：行内代码块、JSON 键名、URL、API 路径、数据库字段名。
-  - 例：`user_id`、`/api/example`、`statusCode` 保持原样。
-
-### 2.5 术语大小写归一
-仅对可见正文中的自然语言短语做归一，不作用于代码、路径、字段和配置项字面量。
-
-| 错写 | 推荐 |
-|------|------|
-| `id` / `Id` | `ID` |
-| `http` / `Http` | `HTTP` |
-| `url` / `Url` | `URL` |
-| `json` / `Json` | `JSON` |
-| `api` / `Api` | `API` |
-| `yaml` / `Yaml` | `YAML` |
-| `java` | `Java` |
-| `kotlin` | `Kotlin` |
-| `python` | `Python` |
-| `ruby` | `Ruby` |
-| `swift` | `Swift` |
-| `dart` | `Dart` |
-| `javascript` / `JS` | `JavaScript` |
-| `typescript` | `TypeScript` |
-| `go`（语言名） | `Go` |
-| `sql` | `SQL` |
-| `bash` | `Bash` |
-| `github` | `GitHub` |
-| `docker` | `Docker` |
-| `redis` | `Redis` |
-| `mysql` | `MySQL` |
-| `grpc` | `gRPC` |
-| `graphql` | `GraphQL` |
-| `websocket` | `WebSocket` |
-| `H5`（移动 Web 页面） | `移动 Web 页面` |
-
-### 2.6 中文易错词表
-| 错误写法 | 正确写法 |
-|----------|----------|
-| `阀值` | `阈值` |
-| `登陆系统` | `登录系统` |
-| `布署` | `部署` |
-| `配制参数` | `配置参数` |
-| `回朔` | `回溯` |
-| `标示字段` | `标识字段` |
-| `帐户`（金融语境） | `账户` |
-| `帐号`（平台用户语境） | `账号` |
-| `做为` | `作为` |
-| `截止 X 日` | `截至 XXXX 年 X 月 X 日` |
-| `缩小了 3 倍` | `缩小到原来的 1/3` |
-| `翻了 1 倍` | `变为原来的 2 倍` |
-| `不超过 100 以上` | `不超过 100` |
-
-### 2.7 内容规范
-- 除非有特殊要求，文章内容及代码注释请优先使用简体中文。
-
-### 2.8 文章创建规范
-- 新文章必须存放在 `_posts/` 目录下，文件命名格式必须为 `YYYY-MM-DD-title.md`。
-- 必须在文件顶部使用 YAML Front Matter 指定 `layout`、`title` 等元数据。
-
-### 2.9 排版与结构规则
-- 一个段落只承载一个主要信息点。
-- 长句可以保留，但避免连续堆叠两个以上长句。
-- 列表项要平行，不要有的写定义、有的写宣传、有的写结论。
-- 标题要能反映用途，不要只写抽象名词。
-
-### 2.10 最终检查清单
-交付文章前检查：
-
-- [ ] 是否出现 `你`、`您`、`同学`
-- [ ] 是否出现中文双引号 `""`（应改为直角引号 `「」`）
-- [ ] 中文与英文、数字之间是否需要留白
-- [ ] 是否存在禁用黑话词
-- [ ] 是否存在过强的宣传口吻或感叹号
-- [ ] 文案是否便于扫读
-- [ ] 术语大小写是否归一
-
-## 3. 构建与运行 (Building and Running)
-本项目使用 Bundler 管理 Ruby gem 依赖。每次执行 Jekyll 相关命令前，必须使用 `bundle exec` 以确保使用正确的 gem 版本。
-
-- **安装依赖:**
-  ```bash
-  bundle install
-  ```
-- **本地开发服务器运行:**
-  ```bash
-  bundle exec jekyll serve --livereload
-  ```
-  *(注：开启 livereload 会自动刷新，但修改 `_config.yml` 后需要重启服务器)*
-- **构建静态站点:**
-  ```bash
-  bundle exec jekyll build
-  ```
-  *(生成的静态文件会存放在 `_site/` 目录下)*
-
-## 4. 项目结构 (Project Structure)
-- `_config.yml`: 站点全局配置 (title, url, theme, plugins 等)。
-- `Gemfile` / `Gemfile.lock`: Ruby 依赖管理文件。
-- `_posts/`: Markdown 格式的博客文章存放目录。
-- `_layouts/`: 自定义 HTML 布局模板 (如 `post.html`)。
-- `_includes/`: 可复用的 HTML 代码片段 (如 `google-analytics.html`, `mermaid.html`)。
-- `_plugins/`: 自定义 Ruby 插件 (如用于渲染 Mermaid 图表的 `mermaid_processor.rb`)。
-- `_site/`: 生成的静态站点目录 (已被 Git 忽略)。
-- `.github/workflows/jekyll.yml`: 用于自动化构建和部署的 GitHub Actions 工作流。
-
-## 5. 特定功能 (Specific Features)
-- **Mermaid 支持:** 站点内置了对 Mermaid 的支持。通过 `_plugins/mermaid_processor.rb` 和 `_includes/mermaid.html` 渲染图表，在编写 Markdown 时可直接使用 mermaid 语法块。
+# Jekyll Blog Project Contract
+
+本文件约束本项目内的写作和站点修改。全局规则继续生效；本文件只补充博客项目特有的内容加工、文件格式和验证要求。
+
+## 项目事实
+
+- 这是基于 Jekyll 4.4.1 和 Minima 的中文技术博客。
+- 文章存放在 `_posts/`，文件名使用 `YYYY-MM-DD-english-slug.md`。
+- 站点使用 `jekyll-feed`、Giscus 和自定义 Mermaid 处理插件。
+- GitHub Actions 使用 Ruby 3.4 执行 `bundle exec jekyll build`，并在每天北京时间 08:00 重新部署未来日期文章。
+- `_site/`、缓存目录和 IDE 文件不是文章交付物。
+
+## 写作目标
+
+技术博客的任务不是保存完整工作记录，而是把作者的隐性经验加工成读者能够理解、代入和复用的内容。
+
+写作前先明确：
+
+1. 这篇文章帮助哪类读者解决什么问题；
+2. 读者最可能在哪一步卡住或产生误判；
+3. 作者经过什么证据、失败或取舍才得到当前结论；
+4. 读完后能够带走什么判断方法或可执行做法。
+
+优先写出一个清晰主张。不要为了覆盖所有相关知识，把一篇文章写成完整手册。
+
+动笔前用一句话写出文章主张：希望读者读完后相信什么、改变什么判断，或者能够完成什么动作。案例、解释和章节都应服务于这句话；无法推进主张的内容应删除或移到其他文章。
+
+## 内容加工
+
+- 从具体症状、失败、冲突或常见误区切入，让读者先认出问题，再介绍概念。
+- 把「同行一看就懂」的经验拆开说明：当时看到什么、为什么容易判断错、后来如何验证、什么条件下结论不成立。
+- 原始材料是素材，不是文章结构。不要按聊天记录、提交顺序或工作步骤机械复述。
+- 优先使用真实案例、代码路径、命令输出、前后差异和量化结果。无法验证的数据不要写成事实。
+- 区分通用原则与当前环境限制。机器、版本或项目特有结论必须说明适用范围。
+- 保留必要的失败过程，但只保留能够解释判断变化的部分。流水账、重复尝试和无关日志应删除。
+- 抽象观点必须落到检查动作。不要停在「保持警惕」「结合实际」「提高判断力」；继续说明先检查什么、依据什么继续、出现什么结果必须停止。
+- 用第一人称提供经历和证据，不用第一人称代替论证。重点写清楚哪条新证据改变了原有判断。
+
+## 观点与论证
+
+- 开头优先呈现读者已经遇到的症状、冲突或误判。不要先铺陈行业背景、工具定义和宏观趋势。
+- 在前几段给出核心判断，让读者尽早知道文章准备证明什么。反常识判断必须由后文的事实、案例或推理支撑，不能只作为吸引点击的口号。
+- 观点型文章优先围绕判断标准推进。每个标准说明三件事：检查什么、为什么容易判断错、什么结果下可以继续或必须停止。
+- 一个可执行的方法至少应说明输入、负责人或执行主体、使用的工具、第一步动作和完成标准。答不出这些问题时，应明确它仍是思路或假设，不写成可直接落地的方案。
+- 对数字、案例、政策、性能和外部行为，优先追溯原始出处。找不到来源时，可以作为待验证线索，但不能写成已确认事实。
+- 用改变前提的方式检验结论。预算、目标、平台、版本或约束变化后结论仍完全不变时，检查它是否只是通用套话；结论依赖特定条件时，把这些条件写出来。
+- 为重要结论补充失效条件或反例。边界越清楚，结论越可信，不要把特定项目中的经验包装成普遍规律。
+- 结尾留下可复用的判断原则、最小检查清单或明确的责任边界。不要重复全文摘要，也不要用「未来值得期待」一类空泛展望收尾。
+
+## 文章结构
+
+根据内容选择结构，不固定套用同一个模板。
+
+### 经验与方法文章
+
+建议使用：读者痛点 → 常见误判 → 作者经历或转折 → 方法 → 适用边界 → 可复用结论。
+
+### 观点与判断文章
+
+建议使用：具体问题 → 表面解释 → 核心判断 → 判断标准 → 验证动作 → 失效条件 → 责任边界。
+
+### 故障与修复文章
+
+建议使用：现象 → 影响范围 → 排查证据 → 根因 → 最小修复 → 验证 → 避免复发。
+
+### 源码与架构文章
+
+建议使用：要回答的问题 → 关键调用路径或组件关系 → 设计取舍 → 失败边界 → 可迁移的工程经验。
+
+### 教程文章
+
+建议使用：完成后的结果 → 前置条件 → 最短可运行步骤 → 原理解释 → 常见错误 → 验证方式。
+
+结构服务于主张。章节只有在推进论证时才保留，不要为了显得完整而增加「背景」「优势」「未来展望」等空泛章节。
+
+## 表达方式
+
+- 默认使用简体中文，准确、自然、克制。中文与英文、数字之间保留合理空格。
+- 中文正文使用直角引号 `「」`。代码、路径、字段、URL 和原始引用保持原样。
+- 技术博客允许自然使用第一人称，以说明真实经历、判断和取舍。
+- 允许少量第二人称帮助读者代入，但不要连续说教、假设读者无知或使用营销式召唤。此规则覆盖通用中文写作 Skill 对第二人称的机械禁用。
+- 专业术语首次出现时，用一句大众语言说明它实际解决什么问题。不要只做英文翻译。
+- 一个段落承载一个主要信息点。长短句交替，避免整篇都是列表、定义和规章语气。
+- 重要判断可以单独成段，普通解释保持两到四句一个段落。短句用于强调，不要把整篇文章切成一句一段的口播稿。
+- 列表用于并列条件、步骤或比较；能够用两三句自然说明的内容不要强行列点。
+- 标题优先表达问题、冲突、结果或反常识判断。可以用「现象 + 真正原因」「常见误判 + 修正方法」制造张力，但不能夸大收益或使用「终极」「颠覆」「必看」「最大漏洞」等无法证明的词。
+- 避免宣传腔、假装深刻的抽象词、无信息量的总结和过多粗体。
+
+## 技术内容边界
+
+- 代码应来自真实实现、最小复现或明确标注的示意代码。不要把未经运行的代码描述为可直接使用。
+- 命令、版本、路径、性能数据和外部 API 行为应尽量现场验证；无法验证时明确说明。
+- 引用外部资料时优先使用官方文档或源码，并提供链接。不要虚构来源。
+- Mermaid 只用于调用关系、状态变化或架构层级等文字难以说明的关系。使用 `mermaid` 代码围栏，保持节点文字简短。
+- 不公开凭据、内部地址、个人数据或其他敏感信息。示例必须脱敏。
+
+## Front Matter 与文件规范
+
+新文章至少包含：
+
+```yaml
+---
+layout: post
+title: "文章标题"
+date: YYYY-MM-DD HH:MM:SS +0800
+categories: [分类]
+tags: [标签一, 标签二]
+---
+```
+
+- 文件日期与 `date` 的日期保持一致。
+- Slug 使用小写英文和连字符，保持稳定、可读，不在 URL 中放中文。
+- `categories` 和 `tags` 复用现有命名，避免同义标签重复。
+- 如果有意定时发布，可以使用未来时间；本地构建验证需加 `--future`。否则不要因为随手填写未来时刻导致文章被跳过。
+- 修改现有文章时保留原 URL，除非用户明确要求重命名。
+
+## 修改范围
+
+- 文章任务默认只修改对应的 `_posts/*.md`。不要顺手改主题、布局、依赖或站点配置。
+- 站点功能任务才修改 `_config.yml`、`_layouts/`、`_includes/`、`_plugins/`、`assets/` 或依赖文件。
+- 保留工作区中无关的未跟踪和未提交内容，尤其是 `.idea/`、其他文章和本地缓存。
+- 不自动把文章写入向量记忆，不自动提交、推送或发布；这些操作需要明确请求。
+
+## 验证
+
+文章修改完成后按成本从低到高验证：
+
+1. 检查 Front Matter、代码围栏、占位符、标题层级和中英文排版；确认前三段已经呈现具体问题和核心判断，主要观点后有证据、例子或动作；
+2. 运行 `git diff --check -- <article>`；
+3. 首选 `bundle exec jekyll build`，未来文章使用 `bundle exec jekyll build --future`；
+4. 检查生成页面存在，并搜索标题、关键段落、代码块或 Mermaid 输出；
+5. 涉及布局、样式或交互时，再进行浏览器视觉验证。
+
+当前本机可能出现 Ruby/Bundler 安装版本与 gem specification 不一致的问题。若 `bundle exec` 因环境损坏失败：
+
+- 先区分文章错误与 Ruby 环境错误；
+- 不要为了单篇文章自动重装 Ruby、修改 `Gemfile.lock` 或升级依赖；
+- 可以在不改项目文件的前提下，用本机已安装且与锁文件匹配的 gem 版本完成临时构建；
+- 如果无法安全构建，至少完成 Front Matter、Markdown 和 diff 检查，并准确报告构建阻塞。
+
+主题自身的 Sass 弃用警告属于已知环境噪声，除非本次任务涉及主题升级，否则不要扩展范围处理。
+
+## 完成交付
+
+最终说明应包含：
+
+- 修改或新增的文章路径；
+- 文章主张和主要结构变化；
+- 实际执行的验证及结果；
+- 未验证项、环境阻塞和剩余风险；
+- 是否提交或发布。