crater-devel-review

name	crater-devel-review
version	0.1.0
description	Crater 全仓库代码审查与 PR 描述：纵览 backend/frontend/cli/charts/docs/website 的变更，按核心规范/优化建议分级反馈，并生成双语 PR 描述。用户要求审查 PR、diff、变更或撰写 PR 描述时使用；开始前须应用 crater-devel-shared。

Crater 开发 · Review

开始前先应用 crater-devel-shared。 本 Skill 用于帮助开发者在提交或 PR 前纵览 monorepo 变更、发现问题并撰写 PR 描述。开发规范的完整权威来源是各级 CONTRIBUTING；.github/instructions/* 是引用 CONTRIBUTING 的审查 MUST/SHOULD 清单。GitHub Copilot code review 阶段的行内 / 总览评论格式由 .github/copilot-instructions.md 负责，本 Skill 不强制遵循那套输出形态。

分级与语气

• 评价、总结、统计与描述一律用简体中文。
• 每条问题标注等级：
  • 【核心规范】（MUST）：违反视为阻断性问题。
  • 【优化建议】（SHOULD）：参考改进方向。
• 作为资深导师：礼貌、专业、有建设性；指出问题同时肯定亮点。若某规范在当前场景反而损害质量，明确指出并建议修订对应指令文档。

按目录加载细则

审查命中的目录时，读取对应权威文档并据此判断，不要在评论里另立一套约定：

变更目录	审查依据（规范权威 + 审查清单）
backend/**	backend/CONTRIBUTING.md + .github/instructions/codebase.instructions.md
frontend/**	frontend/CONTRIBUTING.md + .github/instructions/codebase.instructions.md
cli/**	cli/CONTRIBUTING.md；先读 cli/docs/REVIEW.md（CLI 审查入口），契约见 COMMANDS/SPEC/ARCHITECTURE.md
charts/**	charts/CONTRIBUTING.md + .github/instructions/charts.instructions.md
docs/**、website/**	website/CONTRIBUTING.md + .github/instructions/docs.instructions.md

核心规范检查要点（跨目录速查）

• 安全：无硬编码密钥/Token/密码/内网 IP；DAO 与存储层无 SQL 字符串拼接。
• 后端：管理员接口入 Admin 路由、用户接口入 Protected 路由；外部 API 变更同步 swag；HTTP 状态码符合 RESTful；错误信息为清晰英文。
• 作业模板：作业配置字段、模板持久化结构、模板序列化或 clone / template source 变更须检查是否提升对应前端 MetadataForm* version；提升版本时必须有“上一版本 -> 当前版本”的迁移函数并接入模板迁移注册表，旧版本通过链式迁移升级，不支持的更早版本要明确报错。新增或修改作业模板加载 / 解析入口时，必须复用统一模板迁移逻辑，不要手写局部兼容，也不要把任意 JSON 导入误接入作业模板迁移。
• 前端：无硬编码文本（接入 i18n）；翻译 key 使用英文语义 key 并放入合适 domain，不得新增中文 key；新增 / 修改可翻译文案须同步所有语言 translation.json，保证翻译准确和专有名词一致；身份判断用 useIsAdmin()；非幂等操作执行前须有确认弹出框，说明对象和后果；改动 ui-custom/ 等高复用组件须评估影响范围与兼容性（审查时列为核心规范，要求开发者确认）；不易理解的输入 / 配置项须提供帮助图标与 hover tooltip；前端 / UI 改动的 PR 描述须包含相应界面截图。
• Chart：values.yaml / 模板 / 依赖 / 配置项行为或默认值变更须提升 charts/crater/Chart.yaml 的 version 与 appVersion，二者必须保持完全相同的值，并同步 charts/crater/README.md；values-only 可 patch，前后端 API 变化影响应用契约须 minor，不主动 major；版本发布变化须提醒创建 GitHub tag；新增项含英文注释。
• 文档：website/ 应面向平台用户（集群用户与集群管理员）承载部署、使用、管理、排障等产品文档；docs/ 和仓库各级 .md 默认面向开发者 / 贡献者。归档须正确；术语准确（Account=调度队列）；website/ 部署命令无硬编码 Chart 版本，命令附近用 <CraterChartVersionNotice />，代码块内用 <chart-version>，Chart 配置页用 <ChartBadge />。
• 验证记录：后端 / CLI 构建或测试应先确认本地 go version 符合对应 go.mod / CONTRIBUTING；后端 make run 依赖真实配置和网络环境，缺少配置、凭据或集群访问时应要求开发者检查，不要求 Agent 反复尝试。
• 人工检查：最终提交 / 推送 / PR 描述前必须有开发者亲自执行的人工检查结果；文档改动必须由开发者人工阅读检查，不能只依赖 AI 生成或 AI 自检。
• 分支与 PR 准备：提交 / 推送 / PR 前检查当前分支、目标 base、领先 / 落后提交数和修改文件清单；任务分支落后目标 base 时，先提示需要 rebase 或取得维护者明确接受。
• 联动：功能上线同步 website/ 文档；配置结构变更同步 charts/。

审查输出

• 面向开发者自查输出问题清单即可，不要求拆成 GitHub Copilot 的“行内评论”和“总览评论”。
• 优先列出会阻断提交 / PR 的 【核心规范】 问题，再列 【优化建议】；能定位到文件和行号时给出位置，不能定位时说明影响范围。
• 同类重复问题合并说明，指出代表位置和需要统一检查的范围；复杂问题给修复方向，不堆砌大段代码。
• 若没有发现问题，明确说明未发现阻断项，并列出仍建议开发者人工确认的风险点或测试缺口。
• 给修改建议代码时提醒：直接套用 AI 建议可能导致 Workflow 失败，推荐本地参考修改并测试。
• 审查力度保持克制：后端优化建议仅在明显架构违规、重大性能隐患或高价值最佳实践时提出；website/ 空格、基础校对等琐碎问题交由 Workflow，不必评论。

人工检查建议

审查结束时，结合 diff 告诉开发者还需要亲自检查什么，而不是只说“请测试”：

• UI / 前端改动：列出应打开的页面、角色、入口、关键操作和需要截图的状态；如果改了复用组件、hook、表单控件或 ui-custom/，指出可能被牵连的其它页面或流程，要求开发者抽查代表性页面。
• 后端 / CLI 改动：列出建议运行的命令、API 场景、输入输出、权限身份或错误分支。
• 文档改动：列出需要人工阅读的文档、语言版本、链接、术语、示例命令、Chart 版本占位或关键步骤；提醒开发者 AI 生成文档不能直接提交，必须人工阅读判断。
• Chart / 配置改动：列出需要核对的 values、README、版本号、tag、模板渲染或敏感配置项。
• 提交前检查 git status / diff，确认没有把用于记录任务、测试、issue 编号、临时方案或开发过程的 task note / 临时文件纳入提交；除非维护者明确要求，这类文件不应提交。
• PR 前要求开发者查看最终文件清单、关键 diff 和 PR 描述；若审查发现需要修改的问题，先迭代处理，再生成或更新 PR 描述。

PR 描述生成

根 CONTRIBUTING.md「Open And Iterate On A Pull Request / 创建并迭代 Pull Request」定义 PR 描述必须包含的信息；具体生成流程、模板、AI / 开发者测试分组与拒绝条件以 crater-devel-shared 的「PR 描述」为准。

生成 PR 描述前，必须询问开发者亲自做过哪些人工检查，并要求其提供具体页面操作、命令场景或文档阅读检查。若用户尚未说明关联 issue，必须询问是否有关联 issue；有则按 GitHub 可识别格式写入（如 Resolve #123），没有则省略。文档改动必须要求开发者说明已阅读检查的文档、语言版本、链接、术语、示例命令、版本占位或关键步骤，并确认是否需要调整。Agent 可以加入自己实际执行过的验证，但必须标注为 AI 执行；如果开发者不提供亲自检查结果，或文档改动没有开发者阅读检查结果，拒绝创建 PR 描述。

若需要创建或更新 PR，必须先把最终 PR 描述展示给开发者并取得确认；不能把开发者没看过的 AI 生成文本直接用于 PR。

PR 后续迭代

创建 PR 后提醒开发者检查 workflow 状态；如工具可用，可帮助读取 workflow 状态和 PR 链接。若 workflow 失败，先读取失败 job / log，判断根因与是否和本 PR 相关，再给开发者修复方案。处理 Copilot review 或人工 review 时，先读取意见并判断其是否正确、是否值得修改，再给开发者修改方案。未经开发者讨论和确认，不要直接按 workflow / review 意见修改代码。