薛小嵩blog

AGENTS.md

AGENTS.md

这个仓库的主要用途是记录和维护个人博客文章，不是一个需要做通用前端、Node.js 或 npm 开发的项目。

在这个仓库里工作的 agent，默认应当优先处理文档编辑、文章结构整理和配图管理。不要因为仓库里存在 Jekyll 主题文件、package.json 或模板脚手架，就主动去做 JS、npm、主题模板相关修改，除非用户明确提出这类需求。

仓库定位

  • 主要内容位于 _posts/。
  • 大多数用户请求都应优先理解为：修改 Markdown 文章及其引用图片。
  • _layouts、_includes、_sass、assets、docs、test 等目录属于主题或演示环境，通常不要主动修改。

文章规范

  • 文章存放路径采用 _posts/YYYY/MM/。
  • 文件名格式为 YYYY-MM-DD-slug.md。
  • 每篇文章开头使用简洁的 YAML front matter，形式如下：
---
layout: article
title: 文章标题
tags: 标签
---
  • 除下述更新日期规则或用户明确要求外，保持现有 front matter 风格。
  • 普通文章默认使用 layout: article。
  • 中文文章标题直接使用中文，不要无故改成英文。
  • tags 可以是单个标签，也可以是与现有文章一致的空格分隔标签列表。

文章更新日期

  • 首次发布时不添加更新日期；发布日期继续由文章日期确定。
  • 已发布文章发生实质内容修订时，在 front matter 中新增或更新 last_modified_at: "YYYY-MM-DD"，填写修订实际完成的日期（Asia/Shanghai）。仅修正错别字、调整排版或重新构建站点时，不刷新这个日期。
  • jekyll-sitemap 用 last_modified_at 生成该文章的 <lastmod>；文章页脚也优先用它显示“最后更新”并输出 dateModified。以后统一维护这个字段，不同时填写不同值的 modify_date。
  • 不根据文件修改时间、Git 提交时间或构建时间自动批量改写旧文章的更新日期；没有可靠修订日期的文章保持原样。

图片规范

  • 文章配图优先放在 img/YYYY/MM/DD/ 下，并与文章日期对应。
  • Markdown 图片引用使用站点根路径，例如：
![说明](/img/2025/12/30/example.png)
  • 为某篇文章新增图片时，优先复用该文章对应日期目录。
  • 不要主动重构旧图片目录，除非用户明确要求整理。

自制配图与附属文件

  • 正文只展示最终图片和必要的图解，默认不放 TeX、PDF、SVG 或其他制作文件的下载链接。img/YYYY/MM/DD/ 只放实际用于正文展示的版本，默认使用白底 PNG。
  • 可编辑源码与制作产物统一放在 _article_assets/YYYY/MM/YYYY-MM-DD-slug/，目录名与对应文章文件名（去掉 .md）一致，便于识别归属和二次修改。多张图使用有含义的独立文件名。
  • 附属目录采用以下结构：
_article_assets/YYYY/MM/YYYY-MM-DD-slug/
├── README.md       # 对应文章、文件用途、依赖、重建命令与来源
├── source/         # 唯一的可编辑绘图源文件及必要输入
├── exports/        # PDF、SVG、透明 PNG 等可复用导出版本
├── build/          # 编译中间文件、日志和排版检查图片
├── render.py       # 或适合该绘图工具的重建脚本
└── .gitignore      # 排除 /build/
  • 源码、导出文件与重建脚本保存在博客仓库中；中间文件留在附属目录的 build/，由 Git 忽略。不要把临时目录作为唯一制作源，也不要维护多份相互漂移的源码。
  • 重建脚本根据自身位置解析路径，生成导出版本并更新正文图片，不依赖某次会话的临时路径。README.md 说明如何修改与重建，使用相对路径关联文章和图片。
  • _article_assets/ 保持为 Jekyll 默认不发布的下划线目录，不将其加入 include 或配置为 collection。为文章制作和维护配图时，可以直接维护该目录，无需因其位于 _posts/ 外另行确认。
  • 默认不添加署名、作者名、水印或品牌标记，包括“五道口纳什”；只有用户明确要求时才添加。
  • 多排或多阶段的图必须明确衔接关系：用连接箭头和简短标注说明中间结果如何延续、循环何时结束，以及箭头表示计算、搬运还是同一状态的延续，避免看起来像独立流程。
  • 正文围绕图解释符号、阶段关系和关键限制。区分逻辑张量形状与物理存储/线程布局，技术细节保留必要来源，不把示意图当成实际硬件布局或性能测量。
  • 修改后重新渲染并目检最终图片，检查公式、形状、连接线、文字遮挡和裁切，同时验证正文图片引用有效。同步更新导出版本；不自动提交或发布。

编辑原则

  • 优先做小范围、局部性的文章修改。
  • 在没有明确要求重写的情况下，尽量保持作者现有的结构、术语和表达风格。
  • 如果要优化文章，优先关注这些方面：
    • 错别字和明显病句
    • 表达是否更清楚
    • 小节结构是否更顺
    • 公式和配图说明是否完整
    • 文中图片引用是否一致
  • 不要引入与当前文章无关的重构。
  • 不要主动修改站点主题、npm 工具链或 Jekyll 配置，除非用户明确要求。

默认行为

  • 在需求不明确时，默认把任务理解为“文档相关任务”。
  • 优先修改 Markdown 文章和补充图片引用，而不是改模板或构建链路。
  • 如果一个请求存在歧义，在动 _posts 以外的渲染或构建文件前，先确认是否真的需要修改那些内容。

Git push 的等待经验

2026-09-22 推送 CodeMidas 章节编号修改（02548c2）时，首次 push 被沙箱网络权限拦截；获得权限后的 git push origin main 长时间没有输出，但原进程最终正常退出，返回 22ec852..02548c2 main -> main，推送成功。当时本机 SSH 配置将 GitHub 连接指向 ssh.github.com:443。

  • 无输出不代表失败。 工具返回运行中的 session ID 时，继续等待该 session 的最终输出和退出码。此仓库的 GitHub SSH 推送曾出现超过一分钟无输出后成功的情况，不要仅因短时间沉默就中断或重复 push。
  • 等待时每次约 10–30 秒轮询原进程，避免每几秒反复查询；持续等待期间约每 60 秒向用户说明“仍在等待连接或推送结果”，不要提前报告失败。
  • 原 push 仍在运行时，不并发发起第二次 push，也不要急于改用很短的连接超时。确需重试时，先确认原进程已经结束；若结果不明确，先核对远端分支是否已包含目标提交。
  • 区分明确的权限错误与连接等待：Operation not permitted 等沙箱拒绝需要按当前环境权限规则处理；单纯无输出则先等待。不要把一次会话的权限限制当成仓库长期需要额外授权的要求。
  • 以退出码和远端更新结果确认成功；向用户汇报时明确区分“首次失败”“后续仍在等待”和“最终成功”。

中文技术博客的写作偏好

用户在 2026-09-19 选定 Zartbot、苏剑林、BBuf 作为写作参考。允许借鉴三者的通用叙述方法，保持自己的表达，不复刻标志性措辞或冒充作者。

参考目录：/Users/yxc/code/own_log/2026/09/19-ai-infra-writing-references/README.md。目录内有三位作者的阅读摘记、原文链接、短摘录，以及 SM120 的三份评审样稿。先读与当前题目相关的一份，无需每次全部读取。

  • Zartbot：适合 GPU、网络、系统架构与产品取舍。以工作负载或反常现象引出观点，再解释设计和代价。
  • 苏剑林：适合优化器、Attention、算法细节与公式。围绕一个具体疑问逐步推导，符号和公式随问题引入，用算例落地。
  • BBuf：适合 CUDA、Triton、框架与源码笔记。从代码现象或真实 trace 入手，沿关键调用关系解释原因，避免无关代码堆积。

默认组合：用 BBuf 式源码推进组织工程文章，用问题与推导连接关键数字，架构延伸采用工作负载视角。用户指定某种侧重时优先遵循；不要每篇都硬套三种方法。

具体写法：

  • 从代码、实际问题或疑问开篇，直接进入主题。允许自然口语和有依据的个人判断。
  • 用连贯段落把前因后果讲出来。小标题只服务于明显转折，避免每两三句话一节、层层 A/B/C 编号、不断列表总结。
  • 已经解释过的结论不再换成表格、流程图、加粗句反复讲；表格只留给真正需要并排比较的数据。
  • 核实与阅读可以严格，成文不必像评审报告。重要前提在相关处交代一次，减少“不能据此断言”“不等价于”“最终仍需”等反复打断阅读的措辞。
  • 源码、公式和性能结论仍需核实并保留必要来源；“不那么严谨”指行文自然，不是允许技术错误。
  • 区分实测、手算、资料结果与推断，但不要每段都附免责声明。不得虚构作者的实验、工作经历、团队内部资料或厂商设计动机。
  • 新的风格试写先保留原稿，候选版本放在 own_log 的 review 目录。除非用户要求，不把多个候选都放入 _posts/，不自动提交或发布。
搜索