@routerhub/agent-rules 1.5.86 → 1.5.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/package.json +2 -1
  2. package/skills/create-doc/SKILL.md +68 -0
  3. package/skills/create-pr/SKILL.md +93 -0
  4. package/skills/deploy-test/SKILL.md +72 -0
  5. package/skills/figma-to-code/SKILL.md +58 -0
  6. package/skills/tdd-workflow/SKILL.md +83 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.86",
3
+ "version": "1.5.87",
4
4
  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
5
5
  "main": "AGENTS.base.md",
6
6
  "bin": {
@@ -9,6 +9,7 @@
9
9
  "files": [
10
10
  "AGENTS.base.md",
11
11
  "rules/",
12
+ "skills/",
12
13
  "merge.js",
13
14
  "AGENTS.private.example.md",
14
15
  "PULL_REQUEST_TEMPLATE.md",
package/skills/create-doc/SKILL.md ADDED
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: create-doc
3
+ description: >-
4
+ 创建/生成符合项目规范的 HTML 文档或报告。触发场景包括但不限于：
5
+ 「写文档」「写个文档」「写一个文档」「写报告」「写个报告」「写一个报告」「写需求文档」「写需求」「写说明」「写说明文档」「写方案」「写方案文档」「写设计文档」「写技术文档」「写接口文档」「写API文档」「写总结」「写总结报告」「写复盘」「写复盘报告」「写周报」「写日报」「写月报」。
6
+ 「出文档」「出个文档」「出一个文档」「出报告」「出个报告」「出一个报告」「出需求文档」「出方案」「出方案文档」「出设计文档」「出说明」「出说明文档」「出总结」「出总结报告」「出复盘」「出复盘报告」。
7
+ 「生成文档」「生成报告」「生成需求文档」「生成方案」「生成说明」「生成设计文档」「生成总结」「生成复盘」「生成汇报」。
8
+ 「做文档」「做个文档」「做报告」「做个报告」「做汇报」「做个汇报」「做方案」「做个方案」「做总结」「做个总结」。
9
+ 「搞文档」「搞个文档」「搞报告」「搞个报告」「整文档」「整个文档」「整报告」「整个报告」「弄文档」「弄个文档」「弄报告」「弄个报告」。
10
+ 「文档」「报告」「需求文档」「汇报」单独说且上下文在讨论产出物时也应触发。
11
+ 自动生成符合项目规范（HTML格式、中文文件名、base64内嵌图片、lightbox图片放大、截图为主文字为辅）的中文HTML文档，存放到docs/目录。
12
+ ---
13
+
14
+ # 创建 HTML 文档
15
+
16
+ 生成符合项目规范的中文 HTML 文档/报告。
17
+
18
+ ## 文档规范
19
+
20
+ ### 格式要求
21
+
22
+ - 所有新建文档使用 HTML 格式（`.html`），禁止 Markdown（`.md`）
23
+ - 文件名使用中文命名，存放到项目 `docs/` 目录
24
+ - 标题、正文、章节、说明文字全部中文
25
+ - 代码、命令、专有名词、接口字段可保留英文
26
+
27
+ ### 可视化优先
28
+
29
+ - ⚠️ 核心内容优先用截图、图片、流程图、对比图等可视化形式表达
30
+ - ⚠️ 截图为主、文字为辅（截图占主导版面，文字仅作简要说明）
31
+ - ⚠️ 每段说明文字紧挨其对应截图（「说明→配图」紧密组合）
32
+
33
+ ### 图片处理
34
+
35
+ - ⚠️ 所有图片以 base64 data URI 形式内嵌到 HTML 中，禁止引用外部图片文件
36
+ - ⚠️ 所有图片必须支持点击放大、全屏查看（lightbox 遮罩层）
37
+ - lightbox 实现：图片绑定 click → 弹出半透明黑色遮罩 → 图片居中自适应 → ESC/点击背景关闭
38
+
39
+ ### 报告结构
40
+
41
+ ```html
42
+ <!DOCTYPE html>
43
+ <html lang="zh-CN">
44
+ <head>
45
+ <meta charset="UTF-8">
46
+ <title>文档标题</title>
47
+ <style>
48
+ /* lightbox 样式 */
49
+ /* 正文排版样式 */
50
+ </style>
51
+ </head>
52
+ <body>
53
+ <h1>文档标题</h1>
54
+ <!-- 说明文字 + 配图 紧密组合 -->
55
+ <!-- 重复：说明 → 配图 → 说明 → 配图 -->
56
+ <script>
57
+ // lightbox 交互脚本
58
+ </script>
59
+ </body>
60
+ </html>
61
+ ```
62
+
63
+ ### 截图规范
64
+
65
+ - 截取整页（full page），不是可视区域
66
+ - 截图结果必须包含当前页面 URL
67
+ - 标注（箭头、提示文字等）放在页面空白区域，不覆盖页面内容
68
+ - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
package/skills/create-pr/SKILL.md ADDED
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: create-pr
3
+ description: >-
4
+ 创建 / 提交 / 发起 Pull Request。触发场景包括但不限于：
5
+ 「提PR」「提个PR」「提一个PR」「提交PR」「创建PR」「发起PR」「开PR」「开个PR」「搞个PR」「弄个PR」「弄一个PR」「来一个PR」「帮我PR」「帮我提PR」「帮我提交PR」「帮我创建PR」「帮我开PR」「帮我弄PR」「帮我搞PR」「创建pull request」「提交pull request」「发起pull request」「新建PR」「新建pull request」「生成PR」「生成pull request」「做PR」「做个PR」「做一下PR」「做下PR」「整PR」「整个PR」「整一个PR」「出PR」「出个PR」「出一个PR」「搞PR」「来PR」「上PR」「上一下PR」「帮我上PR」。
6
+ 任何包含「PR」「Pull Request」「pull request」且表达创建/提交/发起语义的说法都应触发。
7
+ 以及：「把这个提交一下」「把这个提了」「提上去」「提交上去」「推到远程」「推到仓库」「发到仓库」「合到主线」「合入主线」「合并到main」「合并到master」「合并请求」「创建合并请求」「发起合并请求」「帮我合一下」「帮我合并」「帮我合了」「把这个合了」「合一下」「合了」。
8
+ 自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中。
9
+ ---
10
+
11
+ # 创建 Pull Request
12
+
13
+ 从当前分支创建 PR，自动完成：中文 Description、效果截图制作、GitHub CDN 上传。
14
+
15
+ ## 核心流程
16
+
17
+ ### 1. 收集改动信息
18
+
19
+ ```bash
20
+ git diff origin/main...HEAD --stat
21
+ ```
22
+
23
+ 确认改动范围，判断 PR 类型（UI 改动 / 接口改动 / 修 bug / 新功能）。
24
+
25
+ ### 2. 查找关联需求文档
26
+
27
+ 自动搜索 `docs/` 目录下对应的需求文档（HTML 格式），匹配当前分支名关键词。
28
+
29
+ ### 3. 生成 PR 内容（全部中文）
30
+
31
+ **Title**：`[模块] 动词 + 改了什么`，祈使句，一行说清。
32
+
33
+ **Description** 模板：
34
+ ```markdown
35
+ ## 背景
36
+ （为什么要改，解决什么问题）
37
+
38
+ ## 改动
39
+ （改了什么，采用什么方案）
40
+
41
+ ## 方案取舍
42
+ （为什么选这个方案，考虑过什么替代方案）
43
+
44
+ ## 不在本 PR 范围
45
+ （有意不做的事、已知局限、后续 follow-up）
46
+
47
+ Closes #issue编号
48
+ ```
49
+
50
+ **Test Plan**：写明验证步骤，禁止「测了没问题」类敷衍描述。
51
+
52
+ ### 4. 制作效果截图
53
+
54
+ 仅对有 UI 改动/修 bug 的 PR 执行：
55
+
56
+ 1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
57
+ 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
58
+ 3. **生成对比图**：用 sharp 拼接 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域矩形框圈选
59
+ 4. **上传 GitHub CDN**：打开 PR 页面 → 评论区 file input 上传 → 获取 `user-attachments` CDN URL
60
+ 5. **写入 Description**：`![](CDN_URL)` 内嵌，清理临时评论
61
+
62
+ **截图规范**：
63
+ - ⚠️ 截图禁止提交到 Git 仓库
64
+ - ⚠️ 必须展示前后对比（修复前红框，修复后绿框）
65
+ - ⚠️ 标注不遮挡页面内容
66
+ - ⚠️ 只截改动相关区域，裁掉无关内容
67
+
68
+ ### 5. 创建 PR
69
+
70
+ ```bash
71
+ gh pr create \
72
+ --title "中文标题" \
73
+ --body "中文 Description（含截图 CDN URL）" \
74
+ --base main \
75
+ --head "$(git branch --show-current)"
76
+ ```
77
+
78
+ ### 6. 补充元数据
79
+
80
+ - Assignees：填自己
81
+ - Labels：按类型/模块添加
82
+ - 关联 issue：如有
83
+ - Milestone：如有
84
+
85
+ ## 重要规则
86
+
87
+ - ⚠️ 一个 PR 只做一件事
88
+ - ⚠️ PR 所有文字内容必须中文
89
+ - ⚠️ 必须附截图作为可视化证据
90
+ - ⚠️ 截图禁止提交到 Git 仓库
91
+ - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
92
+ - 先开 Draft PR，准备好再标记 Ready for review
93
+ - 作者不能 Approve 自己的 PR
package/skills/deploy-test/SKILL.md ADDED
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: deploy-test
3
+ description: >-
4
+ 部署 / 发布到测试环境。触发场景包括但不限于：
5
+ 「部署测试环境」「部署test」「部署测试」「部署到测试」「部署到test」「发布测试」「发布test」「发布到测试」「发布到test」「上线测试」「上线test」「测试环境部署」「测试环境发布」「测试环境上线」「部署测试服」「发布测试服」「上线测试服」「推到测试」「推到test」「推测试」「推test」。
6
+ 「帮我部署」「帮我发布」「帮我上线」「部署一下」「发布一下」「上线一下」「部署吧」「发布吧」「上线吧」「部署了」「发布了」「上线了」「搞部署」「做部署」「弄部署」。
7
+ 「打测试」「打test」「打一下测试」「打个测试包」「打包测试」「打包到测试」「发版测试」「发版到测试」。
8
+ 「部署」「发布」「上线」单独说且上下文在讨论测试环境时也应触发。
9
+ 自动完成：记录当前分支→合并到test→推送→部署→发版→切回原分支。
10
+ ---
11
+
12
+ # 部署测试环境
13
+
14
+ 将当前功能分支部署到测试环境，完成后自动切回原分支。
15
+
16
+ ## 核心流程
17
+
18
+ ### 1. 记录当前分支
19
+
20
+ ```bash
21
+ ORIGINAL_BRANCH=$(git branch --show-current)
22
+ echo "当前分支: $ORIGINAL_BRANCH"
23
+ ```
24
+
25
+ ### 2. test 分支检查
26
+
27
+ 如果 `test` 分支不存在，从主分支创建：
28
+
29
+ ```bash
30
+ git fetch origin
31
+ if ! git show-ref --verify --quiet refs/heads/test; then
32
+ MAIN=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')
33
+ git checkout -b test "origin/${MAIN:-main}"
34
+ git push origin test
35
+ fi
36
+ ```
37
+
38
+ ### 3. 合并当前分支到 test
39
+
40
+ ```bash
41
+ git checkout test
42
+ git pull origin test
43
+ git merge "$ORIGINAL_BRANCH"
44
+ ```
45
+
46
+ ### 4. 推送 test 分支
47
+
48
+ ```bash
49
+ git push origin test
50
+ ```
51
+
52
+ ### 5. 部署 test 分支
53
+
54
+ 按项目自己的部署方式执行（Cloud Run / 容器 / npm publish 等）。
55
+
56
+ ### 6. 发新版本
57
+
58
+ 按项目发版规则执行（如 `./release.sh`）。
59
+
60
+ ### 7. 切回原功能分支
61
+
62
+ ```bash
63
+ git checkout "$ORIGINAL_BRANCH"
64
+ ```
65
+
66
+ ## 重要规则
67
+
68
+ - ⚠️ 推送 test 后必须立即执行 `git push origin test`
69
+ - ⚠️ 部署完成后必须立即切回原功能分支
70
+ - ⚠️ 部署必须自包含：migration、配置变更、依赖检查全部脚本化自动执行，禁止部署后人工补操作
71
+ - 禁止直接往 test 分支提交代码
72
+ - 敏感信息（密钥、Token）必须从 Nacos 配置中心拉取，不得写死
package/skills/figma-to-code/SKILL.md ADDED
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: figma-to-code
3
+ description: >-
4
+ Figma 设计稿还原为代码 / 实现 Figma 设计。触发场景包括但不限于：
5
+ 「figma」「Figma」「FIGMA」出现时。
6
+ 「实现这个设计」「还原这个设计」「按照设计稿」「按设计稿」「照着设计稿」「根据设计稿」「设计稿还原」「设计还原」「Figma还原」「figma还原」。
7
+ 「把这个页面做出来」「实现这个页面」「还原这个页面」「做这个页面」「写这个页面」「开发这个页面」「切这个页面」「切图」「切页面」。
8
+ 「figma链接」「Figma链接」「设计稿链接」「figma地址」「Figma地址」。
9
+ 「从Figma」「从figma」「看下设计稿」「看下设计」「看设计」「看Figma」。
10
+ 任何提供 Figma URL 或提及 Figma 设计稿并要求生成/实现代码的场景都应触发。
11
+ 使用MCP三步验证法：get_design_context（设计意图）→get_metadata（精确坐标）→坐标反推布局，禁止直接使用get_design_context生成的Tailwind代码。
12
+ ---
13
+
14
+ # Figma 设计还原
15
+
16
+ 将 Figma 设计稿还原为代码，以 Figma 文件为唯一事实源。
17
+
18
+ ## MCP 三步验证法
19
+
20
+ ⚠️ **禁止直接使用 `get_design_context` 生成的代码**。`get_design_context` 的输出是大模型推导的近似值，数值和结构均不可信。
21
+
22
+ ### 第 1 步：`get_design_context` → 获取设计意图
23
+
24
+ 用 `mcp__figma__get_design_context` 了解组件整体结构、颜色、字体、视觉效果。
25
+ ⚠️ 仅用于理解设计意图，数值和结构不可信。
26
+
27
+ ### 第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）
28
+
29
+ 用 `mcp__figma__get_metadata` 获取每个节点的真实 x/y/width/height 坐标。
30
+ 这是所有尺寸、间距、定位的唯一事实源。
31
+
32
+ ### 第 3 步：坐标反推规则
33
+
34
+ | 场景 | 反推方法 |
35
+ |------|----------|
36
+ | Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
37
+ | 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
38
+ | 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
39
+ | 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
40
+
41
+ ## 常见踩坑
42
+
43
+ 1. **`get_design_context` padding 不准** → 以 metadata 坐标为基准重新计算
44
+ 2. **按钮被嵌套在文字区域内** → metadata 中同级 x 不同、y 相近 = 横向并排，不应嵌套
45
+ 3. **固定宽度容器被改成全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
46
+ 4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
47
+
48
+ ## 交付验收
49
+
50
+ - 交付前对照 Figma 做视觉和交互验收
51
+ - 发现无法完全还原的素材、字体、数据或平台限制时，明确说明差异和原因
52
+ - 逐项验证：布局、尺寸、间距、颜色、字体、层级、组件状态、响应式规则
53
+
54
+ ## 代码实现规范
55
+
56
+ - 所有尺寸单位使用 `rem`（1rem = 16px）
57
+ - 使用 Tailwind CSS utility classes，禁止原生 CSS
58
+ - 禁止硬编码数字，常量/枚举统一定义
package/skills/tdd-workflow/SKILL.md ADDED
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: tdd-workflow
3
+ description: >-
4
+ 新需求 / 新功能 / 功能开发的 TDD 全流程。触发场景包括但不限于：
5
+ 「新需求」「新功能」「新特性」「新模块」「新增」「添加功能」「加功能」「加个功能」「加一个功能」「做一个功能」「开发一个功能」「实现一个功能」。
6
+ 「帮我开发」「帮我实现」「帮我写」「帮我做」「帮我搞」「帮我弄」「开发一下」「实现一下」「写一下」「做一下」「搞一下」「弄一下」。
7
+ 「需求来了」「有个需求」「来了个需求」「接到需求」「需求是」「要做」「需要做」「需要开发」「需要实现」「需要写」「要开发」「要实现」「要写」「要做」。
8
+ 「功能开发」「功能实现」「业务开发」「业务实现」「代码开发」「代码实现」。
9
+ 「修改代码」「改代码」「改一下」「改一改」「改一版」「改功能」「改一下功能」「修改功能」「调整一下」「调整功能」「优化一下」「重构一下」。
10
+ 「需求文档」「需求分析」「写需求」「需求设计」「方案设计」「设计方案」「出方案」。
11
+ 「开始开发」「开始写」「开始写代码」「开始编码」「开始做」「开工」「动手」「动手吧」「开始吧」「搞起」「开搞」。
12
+ 严格按：需求记录→确认版本→测试先行→基线回归→实现代码→全量回归→上线前回归，七步不可跳过。
13
+ ---
14
+
15
+ # TDD 开发流程
16
+
17
+ 测试驱动开发，每次接收新需求时强制遵循。
18
+
19
+ ## 七步流程
20
+
21
+ ### 第 1 步：需求记录（留痕）
22
+
23
+ 在 `docs/` 目录下新建需求文档（HTML 格式，中文命名），记录：
24
+ - 需求背景
25
+ - 功能范围
26
+ - 验收标准
27
+ - 所属版本号（未说明则归「全量测试」）
28
+
29
+ ### 第 2 步：确认归属版本
30
+
31
+ 明确写入：「归属版本：XXX」或「归属范围：全量测试」。
32
+
33
+ ### 第 3 步：测试先行
34
+
35
+ ⚠️ 先写测试用例，再写业务代码：
36
+
37
+ | 类型 | 位置 |
38
+ |------|------|
39
+ | Go 后端 | `app/supply/`、`app/controller/` 下写 `_test.go` |
40
+ | 前端 UI | `admin_web/e2e/` 或 `user_web/e2e/` 下写 Playwright E2E |
41
+ | API 接口 | `scripts/regression-api-smoke.js` 加冒烟子命令 |
42
+
43
+ 然后在 `scripts/superpowers-regression-runner.js` 的 `TEST_CASES` 中注册新用例。
44
+ 测试用例描述、断言必须使用中文。
45
+
46
+ **测试用例编写规范**：
47
+ - 先写主流程（happy path），再写边界情况
48
+ - 必须模拟真实用户操作：打开页面 → 查看状态 → 点击/填写 → 提交 → 验证结果
49
+ - 覆盖：新建、编辑、删除、查看/搜索、状态流转、异常操作
50
+ - 每条测试用例必须附带对应步骤的截图
51
+
52
+ ### 第 4 步：跑基线回归
53
+
54
+ ⚠️ 改代码之前，先跑一次全量回归建立基线：
55
+
56
+ ```bash
57
+ pnpm run regression:open
58
+ ```
59
+ 确认改动前所有已有用例全部通过。
60
+
61
+ ### 第 5 步：实现业务代码
62
+
63
+ 按需求文档和测试用例实现功能，持续跑新增测试用例。
64
+
65
+ ### 第 6 步：跑全量回归
66
+
67
+ ⚠️ 改完代码后跑全量回归，确认：
68
+ - 新增用例全部通过
69
+ - 所有已有用例仍然通过
70
+
71
+ ### 第 7 步：上线前回归
72
+
73
+ ⚠️ 每次部署生产前，必须跑：
74
+ ```bash
75
+ node 上线回归测试点.js
76
+ ```
77
+
78
+ ## 重要规则
79
+
80
+ - ⚠️ AI 第一反应不是写代码，而是写需求文档 + 设计测试用例
81
+ - ⚠️ 改动必须有迹可循：需求文档 → 测试用例 → 回归报告 → 代码改动
82
+ - 如果用户说「直接改就行不用测试」，必须提醒测试是安全网
83
+ - 测试用例命名含需求关键词，方便追溯