القائمة
Crater monorepo 开发共享基础：仓库结构、文档权威来源、跨模块任务路由与 Agent 全局行为。处理任何 Crater 仓库开发任务前使用；并据此选择应加载的 crater-devel-<domain> Skill。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use Crater CLI admin job commands to list, delete, lock, keep, and clean jobs.
Use Crater CLI job commands to list, inspect, create, stop, and snapshot jobs.
Crater CLI 管理员审批工单域：通过 crater admin order ... 查看、批准、拒绝、清理审批工单。仅在用户明确要求管理员审核时使用。
Crater CLI 用户审批工单域：提交、编辑、取消、查看当前用户的审批工单。管理员审核动作必须使用 crater-cli-admin-approval-order。
Crater CLI 用户视图读取域：指导 AI Agent 通过 crater node、job、image、account、resource、dataset、model-download、pod 等用户可见命令查看平台只读信息。管理员视图请使用 crater-cli-admin-read。
Crater CLI 共享基础：安全调用 crater 命令的通用规则，包括可执行文件选择、全局选项、--json、--no-interactive、--help、错误输出、退出码、错误场景判断、敏感信息处理，以及执行会修改用户环境的命令前的确认规则。处理任何 Crater CLI 操作前使用。
| name | crater-devel-shared |
| version | 0.1.0 |
| description | Crater monorepo 开发共享基础：仓库结构、文档权威来源、跨模块任务路由与 Agent 全局行为。处理任何 Crater 仓库开发任务前使用；并据此选择应加载的 crater-devel-<domain> Skill。 |
Crater 是基于 Kubernetes 的异构（GPU）算力管理平台。本 Skill 是开发该 monorepo 时的入口，处理任何开发任务前先应用本 Skill，再按路由加载对应领域 Skill。
CONTRIBUTING 是开发与贡献的核心完整规范（README 只面向使用者，.github/instructions/* 引用 CONTRIBUTING）。先读对应 CONTRIBUTING 再动手，不要凭记忆推测约定。
更新开发约定时遵循根 CONTRIBUTING.md「Maintaining Development Conventions / 维护开发约定」：影响最终代码、文档、API、UI、Chart 或测试结果的规则，先沉淀到合适的 CONTRIBUTING；.github/instructions/* 作为审查清单引用它；Skill 负责任务路由和 AI 开发过程，并可重复重要约定作为高优先提醒。主要约束 AI 工作方式的规则可直接写在对应 Skill。
| 路径 | 领域 Skill | 权威文档（开发规范） |
|---|---|---|
| 全仓库通用 | crater-devel-shared | CONTRIBUTING.md（根） |
backend/（含 internal/storage/）、frontend/、cli/ | crater-devel-code | backend/CONTRIBUTING.md、backend/cmd/gorm-gen/README.md、frontend/CONTRIBUTING.md、cli/CONTRIBUTING.md → cli/docs/{SPEC,COMMANDS,ARCHITECTURE,REVIEW}.md |
website/、docs/、仓库各级 .md | crater-devel-docs | website/CONTRIBUTING.md |
charts/、grafana-dashboards/ | crater-devel-release | charts/CONTRIBUTING.md、charts/crater/README.md、.github/instructions/charts.instructions.md |
| 全仓库 PR 审查 | crater-devel-review | CONTRIBUTING.md 全套、.github/copilot-instructions.md、.github/instructions/* |
跨模块开发与审查规范见 .github/instructions/codebase.instructions.md（backend/**,frontend/**）。
| 改动 / 意图 | 加载 |
|---|---|
backend/**、frontend/**、cli/** Go 代码 / 测试 / 文档 | shared + code |
website/**、docs/**、仓库各级 Markdown | shared + docs |
charts/**、Helm、Chart 版本、发布产物 | shared + release |
| 审查 PR / diff（任意目录） | shared + review |
| 新增端到端 API | shared + code（如需文档再 + docs） |
用户使用 crater 命令（非改代码） | 不加载 code；用 cli/skills/crater-cli-* |
| 部署 / rollout 到集群、重启服务、镜像 digest 校验 | 集群运维，不属本套；用 crater-rollout |
当用户提出“需要开发”、给出需求、Issue、设计想法或希望实现某项功能时，Agent 先按本流程推进，不要直接修改代码：
CONTRIBUTING 或 cli/docs/*。必要时可先读代码、文档、历史实现来确认边界。git status 与任务相关 diff。把未明确属于当前任务的改动视为开发者已有改动，不要 revert、覆盖或顺手整理；若这些改动影响当前任务，先说明冲突点并与开发者确认处理方式。make install-hooks。检查当前分支是否适合本任务；若在 main 或分支名不符合任务，创建 / 切换到清晰命名的本地任务分支（如 feature/、fix/、docs/、refactor/、test/、chore/ 前缀）。执行 push 前必须确认 fork remote；任务分支只推送到 fork，不推送到 raids-lab/crater 主仓库。git remote -v 识别哪个 remote 是主仓库 raids-lab/crater，哪个是用户 fork。主仓库 remote 可能叫 origin 或 upstream；也可能用户先在 GitHub 上 Sync fork，再从 fork remote 更新本地 main。不要假设 origin 一定是 fork。用正确来源更新本地 main，再将任务分支 rebase 到最新 main，保持线性历史。最终 commit 前和任何 push 前再次确认本地 main 是否落后；若落后，先更新 main，再 rebase 任务分支并重新验证。若远端 / 上游缺失、工作区有未保存改动或 rebase 冲突，先说明情况并按用户意图处理。make pre-commit-check（例如 frontend、backend、website、cli 均支持），必要时再运行根 make pre-commit-check 检查已暂存文件。涉及 Go 子项目时，先检查 go version 是否符合对应 go.mod / CONTRIBUTING。提交或 PR 前使用 crater-devel-review 或对应领域 review 文档做一次阶段性自检；对有效问题完成修改，或向开发者说明保留风险。记录 Agent 实际执行的检查，并提示开发者完成方案阶段列出的人工检查。git commit -s 添加 DCO sign-off，但必须先解释其含义并取得开发者对完整 commit message（包含所有 Signed-off-by 行）的确认，不得静默添加；commit subject 必须符合 type: subject 或 type(scope): subject。commit 创建成功后，立即读取并展示实际写入的完整 commit message、当前分支名和提交包含的文件清单让开发者核对，然后说明下一步通常是整理 PR 描述并创建 PR；进入 PR 阶段前仍需开发者提供其亲自完成的测试 / 人工检查结果，Agent 可同时给出检查建议。复杂任务可使用临时文件辅助整理上下文，推荐路径为 .codex/tasks/<date>-<short-topic>.md（仓库已忽略 .codex）；若不便写入仓库，可用 /tmp/crater-<short-topic>.md。临时 task note 只服务开发过程，不是交付物，除非用户明确要求，否则不要提交。
建议记录：
完整规范见根 CONTRIBUTING.md「Core Engineering Rules / 核心工程规则」与「Start A Change / 开始一次改动」；Agent 额外遵守：
make install-hooks；检查 main 是否最新、任务分支是否符合命名和任务范围，并在需要时 rebase 到最新 main，保持线性历史。远端名称不可假设：origin 可能是 raids-lab/crater 主仓库，任务分支必须推送到用户 fork remote，禁止直接更新主仓库 main 或在主仓库创建分支，除非维护者明确要求。git commit 会触发 pre-commit hook，并对暂存文件涉及的子项目执行对应 make pre-commit-check。该 hook 主要适配 macOS / Linux；Windows 上可能失效，应提示开发者手动运行受影响模块的 make pre-commit-check 或使用 WSL。git commit -s，但必须先解释 Signed-off-by 表示开发者确认自己有权按项目许可证提交贡献，并在执行前展示完整 commit message 给开发者确认；commit 创建成功后再次展示实际 commit message；不得静默添加 sign-off。维护者 squash merge 时保留已有 Signed-off-by，不得替贡献者伪造 sign-off。type: subject 或 type(scope): subject，type 仅限 feat、fix、docs、style、refactor、test、chore；scope 可用于说明改动域，例如 docs(cli): add command examples。完整 commit message 可包含正文和 trailer；DCO Signed-off-by 是 trailer，应放在正文之后，不受 subject 格式限制。The Crater Project Team, RAIDS-Lab，并使用该文件对应的正确年份；新建于 2026 年的文件示例为 Copyright 2026 The Crater Project Team, RAIDS-Lab，项目级 NOTICE 可使用 2023-2026 这样的项目年份范围。make target；存在对应 target 时不要直接调用 go / pnpm / helm。受影响子项目优先运行 make pre-commit-check；需要验证时可自行执行相关命令。crater-devel-review 或领域 review 文档自检；发现问题后先修改或说明风险，再进入 PR 描述阶段。go version。后端 make run / make run-storage 依赖真实配置、Kubernetes、数据库和网络环境，Agent 一般不需要运行；若失败指向缺少配置、网络、凭据、集群访问或管理员才能处理的问题，停下来告知开发者需要检查什么，不要反复尝试。admin 前缀），普通用户调用户接口；前后端两侧需对应。website/ 文档。charts/，提升 charts/crater/Chart.yaml 的 version 与 appVersion，并保持二者为完全相同的值，同时同步 charts/crater/README.md；版本级别与 GitHub tag 提醒遵循 charts/CONTRIBUTING.md。make install-hooks；本地配置使用统一配置管理（make config-link、make config-status、make config-unlink、make config-restore）。Agent 可指引开发者管理配置，但不能代替管理员提供私有配置。Git hooks 见根 CONTRIBUTING.md「First-Time Setup / 第一次准备环境」，本地运行和配置见「Local Debugging / 本地调试」。根 CONTRIBUTING.md 只定义 PR 描述必须包含哪些信息；本节定义 Agent 生成 PR 描述时的具体流程、模板和拒绝条件（crater-devel-review 同样引用本节）。
核心原则：欢迎 AI 辅助开发、测试整理、PR 描述和 PR 创建，但开发者必须自己理解并把关。Agent 不得在开发者未看过并确认 PR 描述的情况下，直接使用该描述创建或更新 PR。
生成 PR 描述前，Agent 必须先阅读 diff，并整理自己在本轮开发中实际执行过的验证（如 make target、单测、构建、lint、git diff --check、文档链接 / 版本占位检查等）。如果开发过程中使用了临时 task note，应优先从其中提取已记录的 AI 检查、人工检查计划和开发者反馈。这些只能作为 AI 执行的检查 写入 PR 描述。还必须检查 git status / diff，确认没有把用于记录任务、测试、issue 编号、临时方案或开发过程的 task note / 临时文件纳入提交；除非维护者明确要求，这类文件不应提交。
生成 PR 描述前还必须确认分支状态：识别 PR 原分支（head fork / head branch）和目标分支（base repository / base branch），并计算相对于目标分支的领先 / 落后提交数。向开发者展示这些信息供检查；正常 PR 分支应该只领先目标分支。如果存在落后提交，必须提示开发者先 rebase 到最新目标分支，除非维护者明确接受当前状态。
若用户尚未说明关联 issue，Agent 必须询问是否有关联 issue。有则在 PR 描述中使用 GitHub 可识别格式（如 Resolve #123），没有则省略相关区块。
同时，Agent 必须询问开发者亲自做了哪些人工检查，并要求足够具体：
必须清楚告知开发者：PR 描述由开发者负责最终检查和控制，Agent 只协助整理，不得替开发者声称其未做过的人工检查。
如果开发者没有提供任何亲自执行的人工检查，或只给出“没测”“你自己写”“随便写”等无法确认的回答，Agent 必须拒绝创建 PR 描述，并要求开发者先亲自检查后再提供结果。若变更包含文档而开发者没有确认已人工阅读检查，同样必须拒绝。不能用笼统的 “Not run” 替代开发者人工检查，也不能把 AI 自己执行过的命令伪装成开发者检查。
开发者提供人工检查后，读取 references/pr-description-template.md，按该模板生成简洁的双语 Markdown。测试部分必须分开标注 AI 与 Developer；模板中的 <...> 是写作提示，生成时必须替换为真实内容，不能原样输出占位符。如果没有关联 issue，省略最后的 Resolve 区块。整体不宜过长，简单改动给简短描述即可；不要为了凑格式扩写。
输出 PR 描述时，必须一并展示 PR 原分支、目标分支、领先提交数和落后提交数，让开发者检查。若落后提交数不为 0，说明应先 rebase 再开 PR。若后续要用 gh 或其他工具创建 / 更新 PR，必须先让开发者确认最终 PR 描述和分支状态；开发者确认后，Agent 可以继续帮助创建 PR。若不是直接创建 / 更新 PR，而是把 PR 描述提供给开发者复制使用，必须将最终文本放在 markdown 代码框中输出，方便复制。
分支推送到 fork 后，如果 gh 等工具可用，Agent 可以帮助创建 PR；否则用 markdown 代码框输出已经确认过的 PR 描述文本供开发者复制使用。创建或更新 PR 前必须满足：
PR 创建后，提醒开发者检查 workflow 状态；如工具可用，Agent 可以帮助读取状态。若 workflow 失败，先读取失败 job / log，判断根因与是否和本 PR 相关，再给开发者修复方案；未经确认不要直接改代码。若需要处理 Copilot review 或人工 review，Agent 可以自行获取 PR 链接或要求开发者提供链接，阅读 review 意见，判断每条意见是否正确、是否值得修改，再向开发者给出修改方案。未经开发者讨论和确认，不要直接按 review 意见修改代码。