张家训
134 lines
6.0 KiB
YAML
134 lines
6.0 KiB
YAML
# WorkUtils 项目规则
|
|
# https://www.codebuddy.ai/docs/zh/IDE/User-guide/Workspace
|
|
version: 1
|
|
|
|
# ===== 项目信息 =====
|
|
name: workutils
|
|
description: WorkUtils API 文档生成工具
|
|
|
|
# ===== 规则定义 =====
|
|
rules:
|
|
|
|
# 1. 导出目录 —— 禁止全文搜索
|
|
- id: no-export-search
|
|
description: |
|
|
禁止对 export/ 目录进行搜索/读取操作。
|
|
该目录包含导出的 HTML 文件，单文件可达数 MB，ripgrep 默认跳过超长行导致结果不准确。
|
|
condition: "path starts with 'export/'"
|
|
action: "reject"
|
|
fallback: "如需调试导出结果，使用源码模板文件 (templates/apidoc/*.js) + 单元测试验证"
|
|
|
|
# 2. 模板规范 —— 禁止 code-in-string 反模式
|
|
- id: no-code-in-string
|
|
description: |
|
|
禁止在 JS 中用函数返回压缩字符串来重复已有代码。
|
|
典型反模式：SNAPSHOT_JS() { return 'function sendDubboRequest(){...}' }
|
|
这种方式导致：
|
|
- 三层转义地狱 (JS字符串→HTML→JS参数)
|
|
- 无法调试、无法 lint、无法语法高亮
|
|
- 代码漂移：修改 api-doc.js 后快照版不会同步
|
|
正确方式：window.__API_DOC_JS__ = {{JS_JSON}}; // 复用原文
|
|
example: |
|
|
# 错误示例
|
|
function SNAPSHOT_JS() {
|
|
return 'function sendDubboRequest(){var e=buildDubboBody();...}';
|
|
}
|
|
# 正确示例
|
|
var mainJs = window.__API_DOC_JS__; // 由 Java 注入的 JSON
|
|
var override = 'function getActiveDubboCard(){...}';
|
|
var fullJs = override + '\n' + mainJs;
|
|
enforcement: "warn"
|
|
severity: high
|
|
|
|
# 3. 占位符命名规范
|
|
- id: placeholder-naming
|
|
description: "模板占位符统一使用 {{NAME}} 格式，双大写加下划线"
|
|
pattern: "\\{\\{[A-Z][A-Z0-9_]*\\}\\}"
|
|
enforcement: "review"
|
|
|
|
# 4. 大文件读取检查
|
|
- id: large-file-check
|
|
description: |
|
|
读取 >500KB 文件前先检查行数和内容分布。
|
|
超大文件（如压缩后的 JS/CSS、生成的 HTML）不适合直接读取全文。
|
|
condition: "file.size > 500KB"
|
|
action: "warn"
|
|
suggestion: "使用 head/tail 检查文件结构，或使用单元测试验证行为"
|
|
|
|
# 5. 转义函数集中管理
|
|
- id: escape-centralized
|
|
description: |
|
|
HTML/JS/JSON 转义函数统一在 Java 侧或独立工具模块管理。
|
|
避免在 JS 源码中混用多种转义方式（\\、\\\、\\'、' 等）。
|
|
files: ["ApiDocGenerator.java"]
|
|
enforcement: "review"
|
|
|
|
# 6. Git 忽略大型产物
|
|
- id: gitignore-export
|
|
description: "export/ 目录应加入 .gitignore，避免提交大型产物文件"
|
|
action: "suggest"
|
|
suggestion: "echo 'export/' >> .gitignore"
|
|
|
|
# 7. 复杂重构分步提交 —— 避免会话中断丢失工作
|
|
- id: refactor-step-by-step
|
|
description: |
|
|
涉及 ≥4 个文件 或 ≥200 行变更 的复杂重构，必须分多个 commit 完成，避免单次会话中断丢失全部工作。
|
|
典型场景：
|
|
- 字段/类重命名（如 navButtons → navList）会触发多文件交叉引用更新
|
|
- 组件替换（Button → ListView）涉及字段、方法、引用、样式、测试多文件
|
|
- 框架/库升级涉及配置文件、依赖、调用点、文档
|
|
推荐步骤：
|
|
① 第一步：加新常量/CSS/配置项（与旧实现共存）
|
|
② 第二步：替换实现/切换调用点
|
|
③ 第三步：删除旧代码（清理 commit）
|
|
每步完成后提交，便于回滚。
|
|
condition: "涉及文件数 >= 4 OR 变更行数 >= 200"
|
|
action: "warn"
|
|
severity: high
|
|
|
|
# 8. AtlantaFX UI 防中断规则 —— 修改 MainWindow/Theme/CSS 时必读
|
|
- id: atlantafx-ui-pitfalls
|
|
description: |
|
|
修改 MainWindow.java、Theme.java 或 light-theme.css 时，必须遵守以下规则，避免反复修改同一问题导致会话中断：
|
|
|
|
【CSS 优先级】
|
|
- AtlantaFX 的 .label 规则优先级极高，!important 也会被覆盖
|
|
- 导航栏选中文字色：必须用 Java 代码 label.setTextFill(Color.WHITE)，不能靠 CSS
|
|
- ListView 选中态：必须同时覆盖 .list-cell:selected（为空 cell 兜底）和 .list-cell:filled:selected（为非空 cell 设置激活背景）
|
|
- 背景透明：需要完整覆盖 .list-view → .virtual-flow → .clipped-container → .sheet 全链路
|
|
|
|
【ListView 虚拟化】
|
|
- cell 会被 VirtualFlow 复用，updateItem(empty=true) 时必须清理自定义 style class
|
|
- 不要用 getStyleClass().setAll()，会误删 JavaFX 内置 list-cell class；用 removeAll + add
|
|
- 窗口 resize 时 cell 复用会暴露 empty cell 被 selected 的问题
|
|
|
|
【布局】
|
|
- 导航 ListView 用 VBox.setVgrow(ALWAYS) 撑满
|
|
- refreshNavItems() 中不要重新设置 prefHeight/minHeight/maxHeight
|
|
|
|
【修改后自检清单】
|
|
① 小窗口（菜单项少）→ 无滚动条，无底部蓝块
|
|
② 选中菜单 → 文字白色，背景蓝色，左侧蓝条可见
|
|
③ 最大化窗口 → 无额外蓝色块闪现，滚动条在导航栏底部
|
|
files: ["MainWindow.java", "Theme.java", "light-theme.css"]
|
|
action: "warn"
|
|
severity: high
|
|
|
|
# ===== 触发提示 =====
|
|
# 当规则被触发时，AI 会看到这些提示
|
|
messages:
|
|
no-export-search: |
|
|
⚠️ 检测到对 export/ 目录的操作。
|
|
该目录包含导出的 HTML 文件（单文件可达数 MB），不适合搜索/读取。
|
|
请改用源码模板文件 (src/main/resources/templates/apidoc/*.js) 进行调试。
|
|
large-file-check: |
|
|
⚠️ 目标文件 >500KB，可能是压缩产物或大型导出文件。
|
|
建议使用 head/tail 检查结构，或通过单元测试验证行为。
|
|
refactor-step-by-step: |
|
|
⚠️ 检测到复杂重构（≥4 文件 或 ≥200 行）。
|
|
建议分步提交：
|
|
① 第一步：加新常量/CSS（与旧实现共存）
|
|
② 第二步：替换实现/切换调用点
|
|
③ 第三步：删除旧代码
|
|
每步完成后 git commit，避免会话中断丢失工作。
|