# AGENTS.md

## 适用范围

本文件适用于整个 `hexo-theme-keep` 仓库。后续代理在本仓库工作时，必须优先遵守本文件；如果用户在对话中给出更具体要求，以用户要求为准。

## 全局规则

- 默认系统为 macOS，默认 Shell 为 `zsh`，默认包管理器为 `pnpm`。
- 所有面向用户的输出统一使用中文，中文内容使用中文标点。
- 输出需结构清晰，按标题、列表或分段组织，避免笼统表述。
- 禁止读取或分析 `node_modules`、`dist` 目录。
- 禁止删除文件；任何删除操作必须先征得用户明确同意。
- 开始修改前先查看 `git status --short`，不要覆盖或回退用户已有改动。

## 项目概览

- 本仓库是 `hexo-theme-keep`，一个 Hexo 主题包，README 标注支持 Node.js `>=14.0.0`、Hexo `>=5.0.0`。
- `_config.yml` 是主题默认配置入口。
- `layout/**/*.ejs` 是 Hexo 页面、局部模板与模板片段。
- `scripts/**/*.js` 注册 Hexo 事件、过滤器、生成器、辅助函数与自定义标签。
- `source/css/**/*.styl` 是主题样式源码，`source/css/style.styl` 是样式入口。
- `source/js/**/*.js` 是浏览器端主题脚本，`source/js/libs` 为第三方压缩库，除非用户明确要求，不要格式化或重写。
- `languages/*.yml` 是多语言文案，`docs/README_zh-CN.md`、`docs/README_zh-TW.md` 是本地化说明文档。

## 常用命令

- `pnpm format`：使用 Prettier 格式化 `source/js/*.js` 与 `scripts`。
- `pnpm lint:style`：使用 Stylelint 修复 `source/css` 下的 Stylus 样式。
- `pnpm prepare`：安装 Husky 钩子。
- `pnpm exec lint-staged`：按暂存文件执行提交前格式化与样式修复。
- 本仓库没有统一的 `test`、`build`、`dev` 脚本；不要在文档或回复中声称存在统一测试命令。
- GitHub Release 工作流当前使用 Node 16、`npm install` 与 `npm publish`；除非任务要求调整发布流程，不要把 CI 发布链路改成 `pnpm`。

## 依赖与锁文件

- 本地执行已有脚本优先使用 `pnpm`。
- 仓库中存在本地 `package-lock.json`，但未被 Git 跟踪，且 `.gitignore` 忽略 `package-lock.json` 与 `yarn.lock`；不要主动把锁文件纳入提交。
- 如安装依赖会生成或改写锁文件，先说明影响；除非用户明确要求统一锁文件策略，否则不要提交新锁文件。

## 代码规范

- 统一使用 2 空格缩进；局部修改旧模板时优先保持邻近代码风格，避免无关格式化。
- 禁止无语义命名；变量、函数、配置键应表达 Hexo 主题语义或页面职责。
- JavaScript 保持现有 CommonJS 与 Hexo 扩展注册方式，例如 `hexo.extend.helper.register`、`hexo.extend.tag.register`、`hexo.on`。
- JavaScript 遵循 Prettier 配置：单引号、无分号、`printWidth` 为 100、无尾随逗号。
- 需要注释时使用 JSDoc 风格，优先解释函数契约、配置结构、边界条件和 Hexo 生命周期，不写无信息量注释。
- Stylus 遵循 `.stylelintrc.js`，保持 `stylelint-config-rational-order` 与 `stylelint-stylus/standard` 规则。
- Markdown 遵循 `.editorconfig`，保留中文段落可读性，不因格式化破坏表格、链接或标题层级。

## 变更边界

- 新增或调整主题配置项时，同步检查 `_config.yml`、`scripts/helpers/export-config.js`、相关 EJS 模板、前端 JS、样式、语言文案与文档。
- 新增页面模板时，优先放入 `layout/_page`；新增可复用片段时，优先放入 `layout/_partial` 或 `layout/_template`。
- 新增 Hexo 标签时，优先在 `scripts/tags` 下实现，并在 `scripts/tags/index.js` 中注册。
- 新增前端交互时，优先复用 `KEEP` 命名空间与 `source/js` 现有初始化模式。
- 修改样式时，优先复用 `source/css/common/stylus-variables.styl`、`keep-style.styl` 中的变量与 mixin。
- 修改多语言文案时，同步维护 `languages/en.yml`、`languages/zh-CN.yml`、`languages/zh-TW.yml`，避免只更新单一语言。

## 验证要求

- 修改 JavaScript 后，至少运行 `pnpm format`，并检查是否出现无关格式化。
- 修改 Stylus 后，至少运行 `pnpm lint:style`。
- 修改提交相关配置后，检查 `.commitlintrc.js`、`.husky/pre-commit`、`.husky/commit-msg` 与 `package.json` 中的 `lint-staged` 配置是否一致。
- 修改渲染逻辑、模板或主题配置后，如本地有可用 Hexo 站点，应在宿主站点执行 `hexo clean`、`hexo generate` 或 `hexo server` 进行页面验收；如果当前仓库无法直接运行页面，需在最终回复中说明验证限制。
- 完成前运行 `git diff --check`，确认没有行尾空格或冲突标记。

## 提交规范

- 提交信息遵循 Conventional Commits。
- 允许的提交类型以 `.commitlintrc.js` 为准：`feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`build`、`revert`、`ci`、`ui`、`chore`。
- 提交前确认没有把密钥、发布令牌、私有配置或本地 IDE 文件加入版本控制。