一、关联 Issue

RFC：https://gitcode.com/openFuyao/InferNex/issues/153

Issue #153 承载 RFC 层面的动机与目标；本 PR 描述承载具体实现的能力说明与演进记录。后续基于本 skill 的能力增强，请在对应 PR 中更新本文档（见文末「演进记录」）。

二、概述

实现 RFC #153 提议的 InferNex 一键部署 Agent Skill（infernex-deploy，v1.4.0），面向昇腾 NPU Kubernetes 环境。用户在 Agent 会话里用自然语言即可完成 InferNex 的部署、升级、验证与卸载，无需记忆 Helm values 细节。全流程以确认门状态机推进，意图、渲染、预检判定、报告全部结构化：

自然语言说需求 → 填 intent.yaml → C1 配置确认 → C2 预检深度选择
→ render_values.py 确定性渲染（含自检）→ preflight_run.py 预检（38 项清单数据化）
→ C3 报告确认 → helm 安装/升级 → 等待就绪（checkpoint 可续跑）→ 网关推理验证 → C4 交付

范围：InferNex 主 Chart 的全生命周期管理。不含 InferNex-Bridge / LLMISVC（后续版本扩展）。

试用版声明：本版本将部署流程、确定性渲染、预检执行、模型档案的框架一次性定型。框架与预检链路已经活集群验证；完整部署链路（新框架 C1→C4 实机回归）、多 Agent 运行时适配、非 Qwen3-8B 模型的实机部署仍在验证与演进中，欢迎社区试用并反馈问题（反馈将按轮次合入，见「演进记录」）。

三、支持的能力

3.1 部署配置项（均可自然语言指定）

3.2 生命周期操作

四、支持的 Agent 运行时

skill 内置结构化点选交互规范（配置确认、卸载范围、敏感信息采集等场景强制使用）：

所有部署逻辑均通过 kubectl / helm / skill 自带脚本执行，不要求工作区有 InferNex 源码。

五、已验证的场景

更多模型规格与运行时的实机验证将持续补充，欢迎社区反馈。

六、端到端流程

6.1 准备依赖（scripts/bootstrap.sh）

• 默认从 OCI 拉取 Chart：oci://cr.openfuyao.cn/charts/infernex @ 0.0.0-latest；浮动 tag 每次拉取最新（避免缓存漂移装旧镜像），固定版本号命中缓存直接用；远端不可达回退本地缓存并醒目告警
• checker 仅在 C2 门选择运行后 --with-checker 拉取（static.openfuyao.cn，按架构自适应）；旧缓存二进制缺新参数时可 --refresh-checker 刷新
• 不要求用户工作区有 InferNex 源码

6.2 采集与确认（C1 / C2 门）

• 节点 IP 用 kubectl get nodes -o wide + templates/nodes.yaml.tpl，默认不 SSH
• 意图填 templates/intent.yaml.tpl（槽位与默认值见 references/intent_schema.md，null=未提及走默认，禁止臆测）
• C1 配置确认门：render_values.py 先渲染 values（内嵌自检 + 派生项回填），按固定模板渲染确认表（含服务名/预期 LWS/RSG 指向等派生项），选项逐字固定（确认，进入预检 / 修改配置 / 取消）
• C2 预检深度门：硬件检查（约 3–5 分钟）→ 连通性检查（耗时大幅增加，需 SSH 凭据）递进询问，默认均推荐跳过；回答回写 intent.yaml（单一事实源，落盘可审计）

6.3 预检（未通过不得安装）

• 执行器 scripts/preflight_run.py 按 references/checks.yaml（v2，判定命令与触发条件全部数据化）逐项执行：软件检查 S-01~S-22（集群环境 / 安装冲突 / Chart 渲染 / values 校验）+ 硬件检查（checker 结果映射，H/K/B 为其输出契约）
• 报告固定渲染为 preflight-report.json + .md：软件 / 硬件（checker）两节，逐项列出（通过项不折叠），中文检查项名称 + 版本/实测值（如 K8s v1.34.3、metrics-server v0.9.0、每节点 NPU 卡数、容量需求/可用），不展示内部编号；硬性失败附白名单修复提示
• NPU 容量（S-18）默认经 npu-exporter metrics 计算（npu-operator 前置组件），不依赖 checker；checker 已跑时以其 H-04 为准
• C3 报告确认门：有硬性失败时不出现「开始部署」选项；修复走 C3r 白名单勾选后重检

6.4 安装 / 升级

• helm dependency build && helm upgrade --install
• 禁用 --wait：RSG 证书 Job 为 post-install hook，与 helm --wait 死锁；就绪由 6.5 轮询保证
• Helm 返回后立即发 interim 进度（不需用户回复）

6.5 等待就绪（可续跑）

• wait_inference.py 轮询：阶段 A 资源出现 → 阶段 B 推理就绪；就绪 = /v1/models 200 且全部 LWS readyReplicas == 期望副本数（首启常 10–30 分钟，预算 90 分钟）
• 每轮写 checkpoint（wait-state.json / endpoint.json，含 LWS 副本进度供交付回填）；中断后可从 checkpoint 续跑，禁止重装
• 禁止固定 sleep 当门禁、禁止 kubectl logs -f（用 --tail=100）

6.6 推理验证与交付（C4）

• 完成条件：经网关 POST /v1/chat/completions → 200（Pod Running / /v1/models 通都不算完成）
• C4 固定表格交付：模型（实测）、部署形态、Release@namespace（Chart 版本）、Endpoint、推理验证、资源落位（LWS/Pod/NPU 卡）、增强组件与硬件检查状态、耗时、产物路径；失败有 C4b 固定处置选项（重试/继续等待/修改配置/取消）

6.7 卸载（独立路径，跳过部署预检）

固定三项点选，避免误删共用组件：

1. 仅 helm uninstall（轻量）：只删主 release
2. 全部清理：主 release → RSG 扩容 orphan LWS 与残留 CR → PVC → Chart 附属 ns（eagle-eye / nats / scaling-system，先查后删）→ 残留 cluster-scoped 资源（按 release 注解过滤，不盲删）；istio sidecar 等 finalizer 卡 Terminating 有 force-delete 指引
3. 取消

均不删除 LWS Operator、npu-operator、metrics-server 等集群共用组件。

七、安全与交互约束（用户可感知的行为）

1. 确认门必经：C1 配置确认 → C2 预检深度 → C3 报告确认，问题与选项措辞逐字固定；预检报告未经确认不部署（硬性失败时部署选项不出现）
2. 预检硬性问题未解决不安装；自动修复仅限白名单且须用户同意
3. 破坏性操作（改集群资源、卸载）必须用户点选确认
4. 默认不 SSH 到节点（仅连通性检查或节点修复按需采集，且不回显明文）
5. 确定性渲染：模式/拓扑/模型/命名/RSG 字段的 patch 只能由 render_values.py 从 intent 生成，禁止手改；同一 intent 渲染结果 byte-identical
6. 「推理通了才算成功」：必须经网关 POST /v1/chat/completions 返回 200 才交付 Endpoint

八、演进记录

本 skill 后续每次能力增强，请在对应 PR 中于下表追加一行，并同步更新 SKILL.md 的 metadata.version。