onyx-craft-dev 是 Onyx 中用于管理本地 Onyx Craft Kubernetes 开发环境的技能，命令需在待测试的代码检出目录中运行，并复用已有的 Make 目标和 VS Code 任务。实现位于 dev.py，不应以临时生命周期脚本替代。
用途与前置条件 适用于以 kind 集群加 Telepresence 方式开发 Craft 沙箱场景。若 SANDBOX_BACKEND=docker，应改用 Compose 指南；若无需 Kubernetes 沙箱的普通开发，应使用 onyx-dev-stack 技能。需准备 Docker 访问权限及 kind、kubectl、helm、Telepresence v2 工具，Kubernetes 节点镜像需 1.33 或更高版本以支持原生 init 边车，并让 kubectl 与集群支持的版本偏差匹配。
环境检查与启动 make craft-doctor 执行只读检查，失败时以非零状态退出，检查锁定的 backend、dev、EE 依赖，解析有效设置但不打印密钥值，并核对沙箱 PodTemplate 镜像和拉取策略。未设置模型凭据会产生警告，但 doctor 不验证应用登录或许可证状态。使用 kind get clusters、kubectl config get-contexts、telepresence status --format json 查看现状，再用 make craft-up 安装 Helm release 并加载沙箱镜像，仅在镜像缺失时构建，并创建缺失的环境文件同时保留已有文件。.vscode/.env.k8s 与 .vscode/.env.web 应保持私密且不纳入版本跟踪。
集群与本地服务 默认集群为 onyx-dev，应用服务命名空间为 onyx，沙箱 Pod 位于 onyx-sandboxes。切换环境需在运行 Make 或独立命令前导出 CLUSTER_NAME、NAMESPACE 等变量，并在每个终端保持导出。首次连接 Telepresence 需在交互式终端执行 telepresence connect，网络守护进程可能需要 sudo 密码，自动化任务无法应答。连接后可用 VS Code (k8s) 启动配置或 make craft-api 启动本地 API，launch.py 在两种方式下提供一致的环境与重载行为。craft-up 等待基础设施就绪后提示本地服务仍需启动；启动 API 与前端后运行 make craft-ready 通过前端代理验证 API，就绪失败不算启动成功。
镜像刷新 按最小范围选择命令：make craft-check-images 比较本地镜像与检出；make craft-sandbox-image 刷新沙箱镜像与 PodTemplate；make craft-backend-image 刷新集群内 API 与沙箱代理；make craft-refresh-images 刷新两者；启动时可用 deployment/helm/dev/craft-up.sh --rebuild-sandbox-image 强制构建沙箱镜像。镜像检查包含已跟踪和未忽略的源文件（含未提交修改），刷新命令复用匹配镜像并构建变更源。本地 API 与前端修改通常无需构建镜像。沙箱镜像刷新只影响未来创建的 Pod，已有沙箱 Pod 保留原镜像。后端刷新会重启 API 与代理部署，需检查滚动更新结果和报告的镜像 ID。多个工作树共享默认可变镜像标签，不要对同一标签并发构建；独立环境应使用不同集群及 BACKEND_IMAGE / SANDBOX_IMAGE 标签。
迁移与验证 make craft-migration-status 与 make craft-migrate 使用检出的 .venv 和 .vscode/.env.k8s，解析集群凭据、连接 Telepresence，并拒绝与部署不一致的数据库目标覆盖。升级前应停止本地 Onyx API 与 Celery 进程，不要杀掉无关进程绕过检查。迁移失败即操作失败，需先检查错误再重试。用 kubectl 查看工作负载；沙箱故障应检查 onyx-sandboxes 中的 Pod、事件和容器日志。按仓库要求使用前端 URL 验证 API，并分别报告基础设施、应用服务和真实 Craft 操作是否已验证。Craft API 操作需要有效的 Business 或 Enterprise 许可证，本地冒烟测试应使用开发许可证，仅设置 ENABLE_CRAFT 标志并不授予访问权限。
数据保护与磁盘控制 暂停集群前先停止本地启动组合，然后使用 make craft-pause 与 make craft-resume；暂停保留集群数据，恢复会启动节点、等待基础设施并重连 Telepresence，恢复后需重新启动本地服务以还原 API 拦截。make craft-down 会删除集群及其数据，仅在明确要求拆除时使用。make craft-disk 与 make craft-clean 用于清理，清理默认仅预览，只移除标记为本检出的未使用悬挂镜像，保留带标签镜像、容器引用镜像、无标签镜像、kind 运行时镜像和卷。删除工作树前应先执行检出清理，因为删除工作树不会触发资源清理。构建缓存跨项目共享，可用 CLEAN_ARGS=--build-cache 预览其单独清理，仅在范围包含缓存清理时加 --apply，其按七天未使用和 10GB 保留目标计算，并非总磁盘上限。工作流工具变更后应运行 regression 测试：.venv/bin/python -m unittest discover -s deployment/helm/dev/tests -v。