# Changelog 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。 ## [1.5.124] - 2026-08-12 ### Added - 新增「代码解释通俗化」规则（语言与内容）：解释代码或技术概念时必须通俗易懂，优先用生活中的真实例子类比（如「缓存命中就像冰箱里放好了可乐，想喝直接拿，不用每次跑楼下超市」），禁止纯学术式讲解、只堆术语贴定义。目标：让不熟悉该领域的人也能听懂。 ## [1.5.123] - 2026-08-12 ### Changed - 强化「创建 PR 后冲突检查」规则为「每次修改 PR 后都必须检查与主分支冲突」：原先只在创建 PR 时查一次 `gh pr view --json mergeable -q .mergeable`，现在 push 新提交、响应 review 意见重新推送等每次改动 PR 后都必须重新检查并解决冲突。原因：主分支随时可能前进，创建时无冲突的 PR 可能在后续 push 后悄悄变冲突。同步更新 `create-pr` skill 第 7 步与「重要规则」章节。 ## [1.5.122] - 2026-08-11 ### Added - 新增「测试环境功能验证前置铁律」（防止缺表报错误判为代码问题）：在测试环境验证任何涉及新增表/新增字段的功能（如充值、退款、发票，不限于这些）之前，必须先确认数据库表结构已就绪。原因：测试环境 AutoMigrate 默认关闭（见「Go 规则」），新表/新字段不会随代码自动创建，跳过前置检查直接验证，报出的缺表/缺字段错误是环境问题而非代码问题，极易误判。验证前必须显式二选一：① 临时打开 AutoMigrate 开关（用后恢复默认关闭）② 手动执行幂等建表/加字段 SQL（`CREATE TABLE IF NOT EXISTS` / `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`）；遇到缺表/缺字段类报错（`relation ... does not exist`、`column ... does not exist`、`Unrecognized name` 等）时，第一优先级检查表结构是否就绪，禁止直接定性为代码 bug。 ## [1.5.121] - 2026-08-10 ### Added - 新增「用户视角测试铁律」（先模拟用户，再写测试）：写测试用例前必须先站在用户视角写出「用户操作路径」（用户在哪个页面、依次点了什么、填了什么、提交后看到什么），测试代码逐条对应真实路径。凡用户能在页面上操作的功能必须页面驱动——按可用性排序「能手动就手动 → Playwright E2E → agent-browser」——禁止直接调 API 代替用户操作；API 直连只允许用于数据准备和结果核验。原因：API 通 ≠ 用户功能可用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等一整层风险。 - 配套在 `tdd-workflow` Skill 第 3 步「测试先行」新增「用户视角先行」强制流程：① 先列用户操作路径清单再写测试代码；② 前端可操作功能必须页面驱动（Playwright / agent-browser），禁止 `curl` 代替；③ API 冒烟测试仅限无页面入口的纯后端接口；④ 能真实浏览器手动点一遍验证的先手动确认再写自动化用例。 ## [1.5.114] - 2026-08-06 ### Changed - `loop-review` Skill 收敛策略重构：结束条件从「无 🔴 Critical / 🟡 Warning」改为「本轮没有任何值得修的新问题」。原因：实测 PR 走了 10 轮仍未干净，bot 每轮全量重读 diff、总能挖出新的问题（漏报/回归/新代码），「严重度清零」是移动靶、循环永不收敛。现在每轮把 bot 的所有新建议逐条读真实代码判断——值得修就修、口味/过度设计/已处理的 Won't fix 回复切断，某轮无值得修的新问题即结束；最大轮数从 5 降到 3。结束时不要求严重度清零，bot 仍挂着几条判断过不值得修的属正常。 ## [1.5.113] - 2026-08-06 ### Added - 新增创建 PR 后冲突检查规则：创建 PR 后必须先检查与主分支（默认分支）是否有冲突（`gh pr view --json mergeable -q .mergeable`），存在冲突必须先解决（merge/rebase → 解决冲突文件 → 测试通过 → 推送）再交付 review，禁止把带冲突的 PR 抛给 reviewer。 ## [1.5.112] - 2026-08-06 ### Added - 新增 `loop-review` Skill（循环 Code Review / AI 交叉验证循环）：写完代码提交 PR 后，反复「拉取 AI review（Claude Opus 4.6 + GPT-5.5 交叉验证）→ 逐条判断哪些建议值得改 → 改 → push 触发新一轮 review → 直到某轮不再有新问题」。触发词如「循环review」「走一下循环review流程」。 ## [1.5.25] - 2026-06-26 ### Added - 新增分发式 PR 模板：`agent-rules` 在 init/sync/watch 时会把统一的 `.github/PULL_REQUEST_TEMPLATE.md` 同步到各项目，强制 PR 描述包含 Description / Test Plan / Screenshots（UI 改动必须贴前后对比截图）和自查清单；对人（GitHub 网页新建 PR 自动预填）和 AI agent 都生效。 - 新增 PR 描述语言与截图规则：PR Description 必须使用中文编写，方便团队成员阅读理解；涉及 UI 改动、交互流程、页面效果等可视化变更时，必须附上截图或录屏作为证据。 ## [1.5.24] - 2026-06-17 ### Added - 新增镜像版本规则：打包镜像时必须统一使用当前 git 提交的 short hash 作为镜像 tag 和版本号，并在所有服务间保持一致。 ## [1.5.21] - 2026-06-10 ### Added - 新增可视化汇报规则：完成任务后的汇报优先在集成浏览器中打开相关页面并定位到关键位置；涉及配置、官网或其他系统联动时需同时打开所有相关页面，方便直接验证联动结果。 - 新增 HTML 文档可视化表达规则：核心内容必须优先通过截图、图片、流程图、对比图和标注图展示，并在图片内添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字。 ## [1.5.20] - 2026-06-09 ### Added - 新增 Superpowers 安装与缺失处理规则：当前环境无法使用 Superpowers 时，代理需先提示安装或启用；无法安装时必须按 AGENTS 等价流程继续执行，并在交付说明中明确使用的流程。 ## [1.5.19] - 2026-06-09 ### Added - 新增新需求回归测试准入规则：每个新需求必须同步新增或更新自动化回归用例；用户指定版本时归档到对应版本测试范围，未指定版本时归档到全量测试，并在交付说明中列出用例名称、文件、归属范围和执行结果。 ## [1.5.18] - 2026-06-09 ### Added - 新增 Figma 还原规范，要求实现时以 Figma 为唯一视觉与交互事实源，完整还原页面跳转、链接、页面流和交互，不允许按主观想法重设计。 ## [1.5.17] - 2026-06-08 ### Added - 新增文本替换保留格式规则，要求仅修改网站协议、条款、页面文案等文本内容时保留原有结构、格式、样式和布局，除非用户明确要求调整样式。 ## [1.5.16] - 2026-06-08 ### Added - 新增 HTML 文档中文内容规则，要求 HTML 文档标题、正文、章节、说明文字、图注和表格等内容默认使用中文。 ## [1.5.15] - 2026-06-05 ### Added - 新增 PR 描述与测试计划表达规则，要求文字尽量简洁明了，并优先通过页面操作路径和可见结果说明验证过程，减少非必要代码片段解释。 ## [1.5.14] - 2026-06-05 ### Changed - 强化 HTML 文档图片规则，要求所有图片资源以 base64 data URI 内嵌，确保单个 HTML 文件即可完整查看并用于发版。 ## [1.5.13] - 2026-06-03 ### Added - 新增 PR 提交、评审与合入规范，覆盖 PR 粒度、标题、描述、Test Plan、reviewer、作者自查、合入门禁、审阅职责、沟通约定和常见反模式。 ## [1.3.12] - 2026-05-02 ### Added - 新增规则：每次开始实现新需求前，必须先在 `docs/` 目录编写需求说明 MD 文档，至少包含需求目标、需求范围、功能要求、验收标准，必要时补充备注。 ## [1.0.29] - 2026-04-20 ### Added - 新增规则：相关测试用例执行通过后，才允许运行 npm run test:e2e:ui 打开 UI 自动化测试页面。 - 新增规则：编写测试用例时，测试描述、断言说明和相关说明文字统一使用中文。 ## [1.0.28] - 2026-04-20 ### Added - 新增规则：当用户要求“加测试用例”时，必须主动执行 npm run test:e2e:ui，并说明本次主要测试用例名称或编号。 ## [1.0.27] - 2026-04-20 ### Changed - 移除自动化测试规则中“关键步骤之间需间隔 2 秒再执行下一步”的要求。 ## [1.0.25] - 2026-04-20 ### Added - 新增规则：错误处理与日志规范，统一使用 console.error 并要求包含上下文信息。 ## [1.0.24] - 2026-04-20 ### Changed - 在示例私有规则文件中补充测试注释示例。 ## [1.0.23] - 2026-04-20 ### Added - 新增规则：打开 UI 自动化测试后，应明确告知当前业务对应的具体测试用例名称或编号，让开发者清楚当前验证范围。 ## [1.0.22] - 2026-04-20 ### Added - 新增规则：写完业务后，必须自动打开 UI 自动化测试页面，执行 `pnpm run test:e2e:ui`，让开发者手动点击验证功能效果。 ## [1.0.20] - 2026-04-19 ### Added - UI 自动化测试端口被占用时，需自动切换到未被占用的新端口。 ## [1.0.18] - 2026-04-19 ### Changed - 分支管理规范：所有新建分支名称必须使用中文（汉字）或纯中文拼音，禁止英文缩写、数字、拼音与英文混用。 ## [1.0.17] - 2026-04-19 ### Added - 新增分支管理规范：所有新建分支名称必须使用中文拼音或汉字，禁止使用无意义英文缩写。 ## [1.0.16] - 2026-04-19 ### Added - 新增测试用例规范：所有测试用例必须包含中文断言或校验内容，确保覆盖中文场景。 ## [1.0.15] - 2026-04-19 ### Changed - 触发自动更新链路验证发布 ## [1.0.14] - 2026-04-19 ### Changed - 自动更新流程改为直接提交到主分支，无需手动合并 PR ## [1.0.13] - 2026-04-19 ### Fixed - 修复自动更新 workflow 权限问题，使用 PAT token 创建 PR ## [1.0.12] - 2026-04-19 ### Changed - 验证自动更新链路 ## [1.0.11] - 2026-04-19 ### Added - 新增代码注释规范：注释统一使用中文编写 ## [1.0.10] - 2026-04-19 ### Added - 新增中文说明文档 `README.zh-CN.md`，补充安装、初始化、同步和监听的使用说明 ### Changed - README 增加中文说明文档入口 ## [1.0.9] - 2026-04-19 ### Added - 新增 UI 自动化测试规则：UI 自动化测试必须请求真实的后端接口，不允许使用本地 mock 数据或截断真实请求 ## [1.0.3] - 2026-04-16 ### Changed - 精简 README，只保留安装说明与自动监听 `AGENTS.private.md` 的使用方式 - 文档默认引导通过 `pnpm dev` 搭配 `agent-rules watch` 使用 ## [1.0.2] - 2026-04-16 ### Added - 新增 `agent-rules watch` 命令 - 支持监听项目根目录下的 `AGENTS.private.md` 变更 - 监听模式启动时自动执行一次同步，生成最新 `AGENTS.md` - 当监听文件尚不存在时，自动监听目录并在文件创建后继续生效 ### Changed - 更新 CLI 帮助文案，补充 `watch` 子命令说明 ## [1.0.0] - 2024-01-XX ### Added - 初始版本发布 - 基础规则 AGENTS.base.md - 合并工具 merge.js - GitHub Actions 自动发布流程 - 项目接入文档和示例 ### 说明 此版本包含所有 RouterHub 项目的通用编码规范和最佳实践。 --- ## 版本升级指南 ### 从 v0.x 升级到 v1.0.0 此版本为首个公开版本，引入了新的规则体系和合并机制。请按照 README.md 中的步骤在各项目中进行集成。 --- ## 未来计划 - [ ] 支持更多规则定制选项 - [ ] 提供 CLI 配置向导 - [ ] 为不同技术栈（React、Vue、等）提供专用规则 - [ ] 集成其他 linter 配置（eslint 等）