hexo-theme-stellar

# AGENTS.md — Stellar 主题仓库 AI 规范

> 本文件是 hexo-theme-stellar 的 AI 协作唯一权威规范；`CLAUDE.md` 与 `.github/copilot-instructions.md` 只作兼容入口。
> 开发、验证或发布主题时调用 `$stellar-theme-dev`；不可调用时直接读取 `.agents/skills/stellar-theme-dev/SKILL.md`。本文件拥有工程门禁，skill 只编排执行顺序。

## Agent pointers

- 创建、读取或更新 issue 时按 `docs/agents/issue-tracker.md`。
- 新增或重构标签插件时读取 `docs/guides/tag-plugins-style-guide.md`；设计或修改配置、内容 profile、组件、Extension 或语言文案时读取 `docs/guides/contribution-architecture.md`。

## 1. 仓库边界

本仓库以 npm 包形式提供 Stellar 的模板、样式、脚本、默认配置、国际化、主题工程文档和发布产物。

- 本文件只约束主题仓库文件；使用方拥有内容、站点配置、版本引用与部署设施，公开 Wiki 由独立文档仓库维护。修改其它仓库文件时读取其 AGENTS.md，分别执行该仓库流程。
- 仓库内证据优先证明主题契约。只有任务明确包含某个消费站点且仓库内证据不足时，才补充该站点自己的集成验证。
- 当前事实以 `_config.yml`、源码、Schema、测试和 `package.json` 为准；知识库只作发布快照与探索索引。

## 2. 工程约束

- EJS 使用 `<% %>` 控制、`<%- %>` 输出 HTML，变量保持 `var`；复用结构放入 partial，复杂逻辑放入 helper。
- Node.js 脚本使用 CommonJS；`test/` 只引用已声明依赖或 Node 内置模块，主题运行时可使用 Hexo 宿主提供的模块。
- Stylus 的共享变量归 `source/css/_defines/`，通用样式归 `_common/`，组件样式归 `_components/`。
- 主题通过 Hexo + EJS + Stylus 生成产物；宿主拥有构建后处理与部署设施。新增依赖、抽象、配置、兼容层或扩展点须由用户目标或既有契约直接需要，并保持最小范围。

### 浏览器产物

- `source/js/runtime/` 以 `.js` URL 提供原生 ESM，由模块入口加载；生成与宿主后处理须保留模块语义及相对导入，排除该目录的传统 Babel/CommonJS 转译。
- 其它浏览器源码使用 ES2015+；宿主需要转译或压缩时对普通脚本执行，并验证最终输出。主题 CI 的 `ci/gulpfile.js` 是消费方后处理的验证入口，应遵守同一产物契约。

### 长期门禁准入

新增或加强会持续阻断以后编辑、构建或运行的测试、Schema、生成器异常、lint/CI 规则、运行时校验或人工同步要求，或者现有门禁阻挡符合用户目标的正常修改时：

- 当前任务验收用于证明本次结果，不自动成为长期契约。长期门禁只保护已公开接口、架构或工程核心边界、安全或数据完整性，以及用户明确承诺长期维护的行为。
- 硬失败须对应产物不可用、不安全、数据损坏、核心工程流程失效或已发布契约被破坏；仍可使用的精度下降、最佳努力兼容和维护提示使用 warning、诊断报告或任务级验收。
- 断言语义能力和边界，不冻结标题、文案、图标、尺寸、顺序、DOM/CSS 形状、示例内容或当前实现方案。
- 人工维护的事实只有一个权威来源，派生清单和镜像由工具生成；同一区域的正常后续修改无需同步无关 fixture、映射表或说明副本。
- 阶段性迁移或发布门禁写明退出条件；无法证明长期来源和稳定边界时，把检查留在 `/private/tmp/stellar-acceptance-<task>/`。
- 门禁失败是待解释的证据，不自动证明修改错误；正常修改触发失去当前来源或稳定边界的门禁时，删除或降级门禁，不增加例外、兼容层或新的人工同步义务。

完成条件：每项新增或加强的长期门禁都有来源、硬失败影响、唯一所有者、允许的正常修改和适用期限；阻挡正常修改的存量门禁已保留、降级或删除并有对应依据；缺少任一项的检查没有进入日常构建与运行路径。

### 测试保留门禁

- 仓库测试在上述准入基础上，只保护长期架构、工程规范与核心流程：配置与 Schema、安全与兼容边界、共享模型与运行时基础设施、构建、生成、迁移、分发和工程门禁。
- 仅当断言对应长期规范、不依赖当前产品方案，且失败意味着架构或核心流程损坏时，才留在 `test/` 或 CI；具体组件的视觉、文案、尺寸、图标、DOM/CSS 结构和交互细节不属于仓库契约。
- 当前契约不存在的具名负向断言按“兼容来源门禁”审查；没有发布来源时使用通用未知字段、未知值或能力边界测试，不在长期测试中枚举未发布候选。
- 具体需求在 `/private/tmp/stellar-acceptance-<task>/` 编写任务级测试或浏览器脚本；交付时报告命令、场景与结果，然后删除该目录。只有暴露长期架构或核心流程漏洞时，才提炼为组件无关的仓库测试。
- 新需求使旧断言失效时，替换任务级验收并删除过期断言；不为具体需求增加仓库 fixture、测试文件或 `package.json` 命令。

完成条件：本次新增或修改的仓库断言满足长期规范、方案无关和核心损坏三项条件；本次产生的临时验收材料已清理。

### 复用门禁

修改 Shell、Region、Sidebar、Widget、公共组件、标签插件或动态控件时：

1. 先搜索已有 capability、partial/helper/mixin、设计令牌和 `scripts/lib/internal-constants.js`。
2. 控件通过 `ui_classes` 或 `ctx.ui.classes` 选择能力；普通链接和局部受保护值例外登记在 `ci/reuse-rules.js` 并写明稳定边界与理由。
3. 新增共享令牌或内部策略字段时同步保护规则；运行 `npm run reuse:check`。

完成条件：本次修改涉及的受管控件均已分类，没有新增原始 capability 组合类或未登记的受保护值副本。

## 3. 文档

- 设计方案、架构决策、迁移或兼容取舍、发布计划和验收记录统一存放在 GitHub Issues，格式与操作权限按 `docs/agents/issue-tracker.md`；仓库不保存单次方案文档，已删除文档的历史由 Git 保存。
- `docs/guides/` 只保存长期维护规范，`docs/audits/` 保存阶段性审计，`docs/knowledge/` 保存当前行为与修改依据。局部修复、样式微调、单字段配置和普通文档维护直接实现。
- 迁移表按“兼容来源门禁”只描述发布基线与明确外部接缝；预发布候选的取舍留在 Git 历史或相关 Issue，当前知识库只说明最终行为与通用失败语义。
- 机器契约与直接测试随实现保持当前；知识库、CHANGELOG 和版本级 `VERIFICATION.md` 在发版准备时按最终净变化集中同步。纯文档任务和事实纠错即时处理。
- 修改知识库后运行 `npm run knowledge:check`；具体发布步骤见 `docs/guides/release-process.md`。

## 4. 工作流程

### 方案选择

新增或迁移配置声明、注册表、共享抽象或事实所有者时，在确定方案前：

- 区分用户目标与实现手段，逐项定位现有事实来源、编辑者和消费者。优先沿用能承担职责的来源；集中解析或复用代码与人工事实存放位置分别决定。
- 用本次相关的一项日常修改比较沿用现有结构与拟议方案：维护者从哪里找到入口、手工修改哪些事实、哪些结果自动派生。新增所有者、映射或跳转须有现有结构无法满足的具体需求作为依据。
- 用户纠正目标或维护方式后，重新检查依赖原假设的所有者、默认值、接口和验证；按修正后的目标重写方案。功能验证与维护路径核查分别提供证据。

完成条件：能指出每项人工事实的唯一编辑入口、日常修改的完整路径，以及新增维护面的必要性。依据留在本次对话或获准的 Issue；长期指南只保留可复用的决策规则，当前文件分工从源码查证。

### 发布基线

兼容、迁移、公开文档和回归面向最近公开发布版本及明确承诺维护的外部接缝。未发布方案、预览、tarball 和中间提交属于可替换候选，不为被替换候选增加别名、双读、迁移或兼容测试。

### 兼容来源门禁

- 方案及受影响调用链中，为旧输入增加或保留的别名、双读、fallback、legacy adapter、专用拒绝/迁移诊断，以及测试、文档中当前契约不存在的具名规则，均按兼容处理；检查范围包括未出现在 diff 中的关联声明与接口。
- 每项专用兼容必须以发布基线树中的实际输入，或有 Issue/文档与当前消费者佐证的明确外部接缝为来源；未发布候选使用当前通用解析、拒绝和验证路径。
- 删除、替换或合并配置声明、数据形状、接口或协议时，沿生产者与消费者全树追查默认配置、Schema、模型投影、模板与客户端消费者、测试和知识库；同时核对因此失去用途的包装、解析分支和扩展协议，检查从旧标识符扩展到其支撑机制。
- 对受影响的适配分支和扩展协议逐项给出保留依据或清理结果。失去最后一个声明或消费者、且无外部维护承诺的机制随本次变更清理；预发布部署经历本身不构成维护承诺。

完成条件：受影响范围内，每项保留的内部适配或扩展协议均能从当前配置声明或生产者追到实际消费路径；每项外部兼容均有发布来源或明确维护承诺的证据。失去用途的接口、支撑机制和未发布候选的专用语义残留已清理；测试通过与全树搜索结果分别作为行为证据和定位线索，保留依据以逐项核对为准。

### 验证门禁

计划和实施都按实际影响选择最低级别；执行验证前按本次最终 diff 复核，影响收窄时同步降级。路径、文件数量、v2 标签或“公开字段”不单独升级风险；只有证据不足或影响无法界定时才升级。

| 级别 | 适用范围 | 必要证据 |
| --- | --- | --- |
| **F0 文档/收录** | 说明、流程、skill、issue 方案、注释，或许可证/NOTICE/README 等非运行时分发材料及其 npm 收录规则 | 相关格式、链接、引用或事实检查；收录变更用 `npm pack --dry-run` 核对实际清单；知识库改动加 `npm run knowledge:check` |
| **F1 定向**（默认） | 局部 CSS/EJS/浏览器 JS/helper、单个配置字段或可界定行为 | 最近的单测、lint、CSS 编译或渲染检查；Schema 改动执行对应的解析、校验与消费测试 |
| **F2 全仓** | 跨域公共运行时、共享模型/Collection 管线、构建链、依赖、广泛重构，或影响仍不确定 | `npm run check` |
| **F3 分发** | npm 包安装后行为、CLI、迁移、发布或明确阶段验收 | F2 + `npm run integration:check`；仅在准备人工验收制品时运行 `npm run acceptance:prepare` |

- 性能契约相关任务显式运行 `npm run performance:check`；普通 F2 不承担性能基线。发版由 `npm run release:check` 组合性能与知识库门禁。
- 宿主集成属于任务目标且主题证据不足时补充消费方验证；UI 视觉判断仅在用户要求或自动检查无法证明时进行。
- 已通过的高层门禁在后续只修改说明或验收记录时不重复运行；F3 制品以最终内容为准。

完成条件：每个受影响契约都有一项通过的直接证据，验证停在最低充分级别。

### 交付门禁

- 交付本次实现、适用验证和获准的 Issue 更新；未获外部写入授权时在对话中报告证据，按 `docs/agents/issue-tracker.md` 处理。普通开发不提前刷新发布快照。
- 一次提交对应一个需求点；提交格式以 `ci/check-commit-msg.js` 为准。
- 默认把改动保留在工作区；用户明确要求 commit 时才提交，明确要求 push 时才推送。已有授权在本任务范围内持续有效；对照起始状态只提交获准改动，保留无关工作区修改。
- 用户要求发布时，按 `docs/guides/release-process.md` 准备 CHANGELOG、确认版本并执行发布流程。

## 5. Issue 处理

读取、持久化、回复与已解决状态统一按 `docs/agents/issue-tracker.md` 执行，该指南拥有外部写入授权及标签自动化的操作规则。

More agent context in xaoxuu/hexo-theme-stellar

4 other files this repository gives its agents.