@routerhub/agent-rules 1.5.24 → 1.5.25

package/AGENTS.base.md

@@ -25,6 +25,7 @@
 - PR Title 示例：`[auth] Fix token refresh race condition on concurrent requests`、`[payments] Add idempotency key to charge API`、`[infra] Migrate cache layer from Redis 6 to Redis 7`。
 - PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
 - PR Description 必须足够充分，至少回答 What（改了什么）、Why（为什么改，解决什么问题或满足什么需求）、How（采用什么方案，为什么选该方案）。
+- PR Description 必须使用中文编写，方便团队成员阅读理解；涉及 UI 改动、交互流程、页面效果等可视化变更时，必须附上截图或录屏作为证据。
 - PR Description 和 Test Plan 的文字应尽可能简洁明了，优先用页面操作路径、按钮点击、表单输入、可见结果描述验证过程；尽量少用代码片段解释，除非代码是理解变更或复现问题的必要证据。
 - 涉及行为变更、接口变更、数据迁移、性能影响时，必须在 Description 中显式写出。
 - 有意不做的事、已知局限、后续 follow-up 必须写清楚，避免 reviewer 重复追问。
@@ -228,7 +229,7 @@ Closes #456
 ## Docker 与部署
 
 - 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
-- 部署时打包镜像必须统一使用当前 git 提交的 short hash 作为镜像 tag 和版本号；项目内所有服务/镜像都必须使用同一个值，无论该镜像是否有代码改动，确保所有镜像版本号一致后再发版。
+- 部署时打包镜像必须统一使用当前 git 提交的 hash 作为镜像 tag 和版本号；项目内所有服务/镜像都必须使用同一个值，无论该镜像是否有代码改动，确保所有镜像版本号一致后再发版。
 - 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
 - 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。
 - 测试环境和生产环境都通过 Portainer 部署，严禁 SSH 手动操作。测试环境是 Edge Agent（endpoint 7, stack 31），tunnel 按需建立、空闲自动断开，调 API 前必须先请求 `/endpoints/7/docker/info` 预热 tunnel；推荐直接用 `python3 portainer-update-stack.py <VERSION>` 部署（内置 tunnel 预热 + 重试）。生产环境是 Docker API（endpoint 8, stack 26），`APP_VERSION` 三服务共用。

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [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

package/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+<!-- 本文件由 @routerhub/agent-rules 统一管理，请勿手动编辑；改动请提到 agent-rules 包。 -->
+
+## Description
+
+<!-- What / Why / How：改了什么、为什么改（解决什么问题或满足什么需求）、采用什么方案及取舍。 -->
+<!-- 涉及行为变更 / 接口变更 / 数据迁移 / 性能影响时必须显式写出；有意不做的事、已知局限、后续 follow-up 也要写清。 -->
+
+Closes #
+
+## Test Plan
+
+<!-- 硬性必填：如何验证改动正确，附可复现步骤或证据（命令 + 结果、手动操作步骤、日志、请求响应、修复前后对比）。 -->
+<!-- 禁止只写「tested locally / 测了没问题」。 -->
+
+## Screenshots
+
+<!-- UI / 前端改动必须贴截图（整页、含 URL）；行为有变化时贴「改动前 / 改动后」对比。把图片直接拖拽到此处。 -->
+<!-- 纯后端 / 无界面改动写「N/A（无界面变化）」。 -->
+
+## Checklist
+
+- [ ] 一个 PR 只做一件事，无夹带无关改动
+- [ ] Description 已说明 What / Why / How
+- [ ] Test Plan 完整且带证据
+- [ ] UI 改动已贴截图（或注明无界面变化）
+- [ ] 本地编译 / lint / 测试通过，CI 全绿
+- [ ] 已关联 issue、指定 reviewer

package/merge.js

@@ -15,6 +15,7 @@
  *   AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
  *   .github/copilot-instructions.md              全局规则（VS Code Copilot）
  *   .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
+ *   .github/PULL_REQUEST_TEMPLATE.md             统一 PR 模板（GitHub 新建 PR 时预填）
  */
 
 const fs = require("fs");
@@ -35,6 +36,8 @@ function getDefaultConfig() {
     rulesDir: path.join(packageRoot, "rules"),
     baseRulesPath: path.join(packageRoot, "AGENTS.base.md"),
     privateRulesPath: path.join(currentRoot, "AGENTS.private.md"),
+    prTemplateSrc: path.join(packageRoot, "PULL_REQUEST_TEMPLATE.md"),
+    prTemplateOutput: path.join(currentRoot, ".github", "PULL_REQUEST_TEMPLATE.md"),
   };
 }
 
@@ -329,6 +332,17 @@ function generateInstructionFile(
   console.log(`✅ 条件规则已生成: ${outputPath}`);
 }
 
+function syncPrTemplate(config) {
+  const defaultConfig = getDefaultConfig();
+  const src = config.prTemplateSrc || defaultConfig.prTemplateSrc;
+  const output = config.prTemplateOutput || defaultConfig.prTemplateOutput;
+  const content = readFileIfExists(src);
+  if (!content) return;
+  ensureParentDir(output);
+  fs.writeFileSync(output, content, "utf-8");
+  console.log(`✅ PR 模板已同步到 ${output}`);
+}
+
 function mergeAgents(config) {
   const defaultConfig = getDefaultConfig();
   const {
@@ -346,6 +360,9 @@ function mergeAgents(config) {
   console.log(`   规则目录: ${rulesDir}`);
   console.log(`   私有规则: ${privateRulesPath}`);
 
+  // 同步统一 PR 模板到 .github/PULL_REQUEST_TEMPLATE.md（独立于 rules/ 是否为空）
+  syncPrTemplate(config);
+
   // 0. 从 AGENTS.base.md 自动拆分生成 rules/*.md
   generateRulesFromBase(baseRulesPath, rulesDir);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.24",
+  "version": "1.5.25",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {
@@ -11,6 +11,7 @@
     "rules/",
     "merge.js",
     "AGENTS.private.example.md",
+    "PULL_REQUEST_TEMPLATE.md",
     "README.zh-CN.md",
     "postinstall.js",
     "package.json",

package/rules/devops.md

@@ -7,7 +7,7 @@ outputName: "devops"
 ## Docker 与部署
 
 - 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
-- 部署时打包镜像必须统一使用当前 git 提交的 short hash 作为镜像 tag 和版本号；项目内所有服务/镜像都必须使用同一个值，无论该镜像是否有代码改动，确保所有镜像版本号一致后再发版。
+- 部署时打包镜像必须统一使用当前 git 提交的 hash 作为镜像 tag 和版本号；项目内所有服务/镜像都必须使用同一个值，无论该镜像是否有代码改动，确保所有镜像版本号一致后再发版。
 - 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
 - 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。
 - 测试环境和生产环境都通过 Portainer 部署，严禁 SSH 手动操作。测试环境是 Edge Agent（endpoint 7, stack 31），tunnel 按需建立、空闲自动断开，调 API 前必须先请求 `/endpoints/7/docker/info` 预热 tunnel；推荐直接用 `python3 portainer-update-stack.py <VERSION>` 部署（内置 tunnel 预热 + 重试）。生产环境是 Docker API（endpoint 8, stack 26），`APP_VERSION` 三服务共用。