dsh-runnpu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EM-GeekLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# dsh-runnpu
+
+DeepSeek Harness (dsh) 插件：在 RunNPU 昇腾 NPU 集群上提供「算力管理」与「训练」两个 agent 模式。
+
+```bash
+cd ~/.dsh/profiles/web
+pnpm add dsh-runnpu
+npx dsh-runnpu install all --profile web --with-cli
+pnpm install
+```
+
+然后重启 dsh，新建会话时选择模式。`npx dsh-runnpu doctor` 检查配套的 runnpu / swanlab CLI。
+
+配套 runnpu CLI 版本：v0.1.1（发布仓 https://github.com/EM-GeekLab/run-npu-skill ）。
+
+本包只含构建产物；使用与安装说明见 https://github.com/EM-GeekLab/run-npu-harness 。

package/compute-mode/preset/agent.cordis.yml

@@ -0,0 +1,368 @@
+# The `compute` agent preset — 算力管理模式.
+#
+# Derived from the shipped `standard` preset. Two deliberate differences:
+#   1. the persona is a cluster operator, not a coding agent;
+#   2. `skill-filesystem` also scans this preset's own `skills/` tree, so the
+#      RunNPU skill ships WITH the mode.
+#
+# The UI half of this mode (right-hand cluster panel, pinned charts, the login
+# form) is NOT here: it lives in the `dsh-runnpu` bundle on the host
+# plane, and keys off this preset's id through the session's `agentPreset`
+# projection. A preset decides what the AGENT can do; the bundle decides what
+# the WINDOW looks like.
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+# The preset's own persona, shadowing the deployment default for this agent.
+# `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    # dsh ≥ 0.1.5 reads `prefix` (+ optional `suffix`); older harnesses read `text`.
+    # Both point at the same block, so one preset serves both.
+    prefix: &persona >-
+      You are a compute-platform engineer operating a RunNPU Ascend NPU cluster
+      through the DeepSeek Harness, powered by the {{model}} model.
+
+      Answer questions about cluster state, capacity, quota, queueing and
+      workload health using the `runnpu` skill — always read it before acting.
+      Read-only commands you may run directly.
+
+      For per-project questions there are two levels, and picking the wrong
+      one is the usual mistake. `cluster_usage` gives the CLUSTER-WIDE roll-up
+      per project — quota, held, running, held-minus-running. But quota and
+      storage are actually accounted PER POOL, and that detail only exists in
+      `cluster_chart` with query `projects` and source `usage` / `storage` /
+      `queues`: one row per project per pool, with a signed `over_guarantee`
+      (positive = borrowing capacity that can be preempted, negative = paying
+      for a guarantee nobody is using) and storage `used_pct`. When someone
+      asks which project is over, which is wasting, whose disk is filling up,
+      or why a project's queue is not admitting, that is where the answer is —
+      and it is a table they can pin.
+
+      For "who is holding the cards", "how much quota is used" and "what is
+      wrong right now", prefer `cluster_usage` and `cluster_anomalies` over
+      assembling the answer from several CLI calls: those numbers are computed
+      deterministically, so they do not need checking, and the anomaly rules
+      catch things nobody thought to ask about. Report the EVIDENCE each
+      finding fired on, not just its verdict. When capacity is the question,
+      start from `cluster_usage` — held-minus-running is usually the real
+      answer, not the free-card count.
+
+      To STOP, START or DELETE a workload, use the `cluster_workload_action`
+      tool — never the shell. The tool routes the decision through the
+      harness's approval prompt, so the user approves the exact structured
+      action that then runs, and it records the operation either way. A shell
+      command asks in prose and executes something the user never saw. If the
+      user declines, do not rephrase and ask again. This is no longer only a
+      rule you are asked to follow: `runnpu workload delete|stop|start` typed
+      into the shell is REFUSED by a guard before it runs, so reaching for the
+      shell costs a turn and changes nothing. The read-only subcommands —
+      `list`, `logs`, `events`, `endpoints`, `get`, `exec`, `port-forward` —
+      are untouched; keep using them freely.
+
+      To change a project's QUOTA, use `cluster_quota_set` rather than `runnpu
+      project quota set`. The CLI replaces the whole quota block, so changing
+      one pool there means retyping every pool that is to survive, and a pool
+      left out is a pool set to nothing. The tool reads the current quota,
+      applies only the fields you name, and writes once — so name ONLY what
+      changes. What the user sees in the approval prompt is a DIFF ("保底 2 →
+      4 卡"), so restate that same diff in your own words before you call:
+      somebody can only agree to a change they can recognise. To take capacity
+      away, set the pool's numbers to 0 — do not try to remove the pool, and do
+      not fall back to the CLI when the tool refuses something.
+
+      Everything else that changes the platform — creating workloads,
+      membership, users — still goes through the CLI, and there you must
+      restate the parameters and get explicit agreement before running
+      anything. Creating a workload is allowed through the shell and is also
+      RECORDED: the operation log keeps the project, name, type, template and
+      image of what you created — never the command line itself — so "who built
+      this" is answerable later without env values ending up in a log file.
+
+      Quantities carry units and accounting basis: quota is in CARDS, internal
+      accounting uses card-equivalents (100 cores = 1 card). A `null` metric or
+      `metrics.available=false` means the data source is NOT WIRED UP — say so;
+      never report it as zero. Refer to a workload as `<project-slug>/<name>`.
+
+      This session runs with a right-hand cluster panel. `cluster_chart`
+      renders a query as a line chart, a bar chart or a TABLE, and every one of
+      them can be pinned. Pick by the shape of the question: "how did it
+      change" is a line, "who has the most" is a bar, "which ones, with their
+      numbers" is a table. Do NOT hand-write a markdown table of cluster data —
+      it cannot be pinned, it goes stale the moment you send it, and you are
+      retyping numbers you already have. Produce the view and tell the user
+      they can pin it; a pinned view keeps its query and refreshes itself, so
+      it is worth more than anything pasted into the conversation. Ignore the
+      workspace directory: this mode is about the cluster, not about code.
+
+      For a PERIODIC report, use `cluster_report` — never re-derive the digest
+      from `cluster_usage` each time. It reports what CHANGED since the last
+      report, which is the only thing worth delivering on a schedule: a digest
+      that repeats the same findings every morning gets skipped, including the
+      morning a new one appears. Calling it advances the baseline, so use
+      `preview` when merely demonstrating it.
+
+      Schedule the report with `schedule_create`, and tell the user its three
+      real limits BEFORE they rely on it, because none of them is obvious and
+      each one looks like a bug later: (1) delivery is SESSION-LOCAL — the
+      report arrives as a message in THIS conversation, never as mail or a
+      notification, and while the session is closed it simply waits, overdue,
+      until the session is resumed; (2) the interval is fixed-rate from the
+      moment you create it, so "every day" means 24h from now, not 09:00 —
+      state the wall-clock time the first one will land and let the user
+      re-anchor if they wanted a different hour; (3) a session that was already
+      running before reminders were mounted has no `schedule_create` at all.
+
+      Finish each answer by calling `cluster_followups` with the two to four
+      questions THIS answer actually raises — name the workload, node or
+      project you just found something about, or the decision now waiting on
+      the user. They appear as one-click buttons above the composer. Skip the
+      call when nothing genuinely follows; an empty row beats four questions
+      nobody wants.
+    text: *persona
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+# `shell-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
+# publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
+# the criterion for host-plane ownership — injection resolves before any session
+# exists, so there is no agent to key by. Behind a preset realm those variables
+# never reached the model's shell at all. Both shell tools consume the host
+# registry from here; their executors (`bash-sandbox`/`pwsh-sandbox`) are
+# host-plane too.
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+  disabled: !!js process.platform === 'win32'
+
+- id: tool-pwsh
+  name: '@deepseek-ai/dsh-tool-pwsh'
+  disabled: !!js process.platform !== 'win32'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+# Both register into the host `tools` registry and provide nothing, so
+# they need no realm. The `fs` service and its policy stay in the host.
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+
+# ── background jobs ────────────────────────────────────────────────────────
+
+# Only the model-facing controls. The task REGISTRY stays on the host plane:
+# its producers sit outside any realm this file could put it in — `tool-bash`
+# above resolves it with `ctx.get`, and an entry-local realm here is invisible
+# to every sibling row, so `run_in_background` would answer "background jobs
+# unavailable" while these controls sat in the catalog. The registry is keyed by
+# owning agent anyway, so one host instance serves every session. What a preset
+# chooses is whether its agent can collect and stop background work at all.
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── skills ──────────────────────────────────────────────────────────────────
+
+# The skill REGISTRY lives in the host composition and is layered per scope:
+# these rows register into THIS preset's layer of it, so they need no realm.
+# `skill-filesystem` contributes local-root discovery for agents on this preset, and
+# `tool-skill` gives them the catalog and loader; the merged catalog also
+# carries whatever the deployment registered globally (repository plugins).
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+  config:
+    # Rank 300 `custom`: scanned after project roots, before user roots.
+    # These directories ship WITH the preset, so the mode carries its own
+    # skills instead of depending on what the machine happens to have.
+    # `__DSH_PRESET_ROOT__` is substituted with the machine's real preset root
+    # by scripts/install-presets.mjs at copy time — an absolute path baked at
+    # authoring time only works on the author's machine.
+    customSkillDirs:
+      - __DSH_PRESET_ROOT__/compute/skills
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+# ── goals ───────────────────────────────────────────────────────────────────
+
+# Only the model-facing tool. The goal SERVICE, its session driver, and the
+# `/goal` command stay on the host plane: the Gateway serves the goal domain as
+# Remote endpoints whose receiver comes from a generated descriptor, so it
+# resolves `goals` on the host and an entry-local realm here would hide it. The
+# registry is keyed by session anyway, so one host instance serves every
+# session. What a preset chooses is whether its agent can call the goal tool.
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── plan mode ───────────────────────────────────────────────────────────────
+
+# Plan state is per-agent by nature, so an entry-local realm is not a
+# workaround here — it is the correct lifetime.
+- id: planning
+  name: cordis:group
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+# ── compaction ──────────────────────────────────────────────────────────────
+
+# `compaction-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
+# share this realm rather than sit outside it.
+#
+# `tokenMeter` is deliberately NOT in this realm: the meter stays on the HOST
+# plane, and the rows here resolve that one instance. It takes no configuration,
+# keys every fold by Session, and owns the context-meter projection units the
+# browser reads for every session — behind a realm those units would come and go
+# with whichever presets happen to be mounted. What a preset chooses is whether
+# its agent compacts at all, which is `compaction-basic` below.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── delegation and workflows ────────────────────────────────────────────────
+
+# The `subagents` registry and its spawn/fork backends live in the HOST
+# composition: the registry is a process singleton whose cross-session queries
+# the api-proxy serves to the browser, and a provider name may only be
+# registered once. This preset contributes the delegation TOOLS, which resolve
+# that host registry.
+#
+# `workflows` is different — nothing outside an agent reads it — so every row
+# that reaches it shares one entry-local realm here, and a consumer left
+# outside would resolve a host registry this preset does not populate.
+#
+# `tool-subagent-report` is host-plane for the same reason as the registry,
+# not because a preset may not want it: it registers a CONTINUABLE SETUP on
+# that singleton rather than a tool this agent calls, and the setup list is
+# not scope-aware — one copy per mounted preset means every child gets
+# `report` registered once per live session, which throws on the second.
+- id: delegation
+  name: cordis:group
+  group: true
+  isolate:
+    workflowEngine: true
+  config:
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    # Production dsh does not install these optional providers. Install the
+    # matching Bundle in this Profile and restart the Host, then copy this
+    # preset and remove `disabled` from the matching tool row. Host availability
+    # alone grants no tool.
+    - id: tool-subagent-codex
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: codex
+        toolName: subagent_codex
+        backgroundMode: one-shot
+        maxDepth: provider-managed
+
+    - id: tool-subagent-claude-code
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: claude-code
+        toolName: subagent_claude_code
+        backgroundMode: one-shot
+        maxDepth: provider-managed
+
+    - id: workflow-worker-thread
+      name: '@deepseek-ai/dsh-workflow-worker-thread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+# ── remaining model-facing rows ─────────────────────────────────────────────
+
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+# The `web` service and its search provider stay in the host composition; only
+# the model-facing tool is per-session.
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: false
+    searchTimeoutMs: 60000
+
+# ── cluster chart tools ─────────────────────────────────────────────────────
+
+# Charting and the pinned-chart registry. They register into the host `tools`
+# registry and publish nothing, so they need no realm.
+#
+# The agent answers most cluster questions through the `runnpu` CLI skill;
+# these exist for the one thing a CLI cannot do — put a chart on the screen and
+# keep it there. `cluster_chart` renders in the conversation with a Pin button;
+# `cluster_pin` stores the QUERY plus why it was pinned, never a snapshot, so
+# the right column is always current and still self-explanatory.
+- id: compute-tools
+  name: 'dsh-runnpu/compute/tools'

package/compute-mode/preset/preset.yml

@@ -0,0 +1,3 @@
+name: 算力管理模式
+description: 面向 RunNPU 集群的算力运营工作台：查看总览、节点与逐卡健康、项目配额、排队与闲置负载，并把产出的图表固定在右栏自动刷新。忽略工作目录。
+order: 10

package/compute-mode/preset/skills/runnpu/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: runnpu
+description: 通过 runnpu CLI 操作 RunNPU 昇腾算力平台——查看总览 / 节点 / 集群，管理项目、配额与成员，创建、排查、删除四类工作负载（开发环境、训练环境、训练任务、推理服务），使用工作负载模板与资产，挂载数据源与数据卷，读日志、事件、指标与 YAML，管理用户 / Access Key / 系统设置 / 审计。凡是用户要"在 RunNPU 上做某事"或询问平台 / 集群 / 负载现状时使用。
+---
+
+# RunNPU CLI Skill
+
+RunNPU 是面向昇腾 NPU 的算力管理平台。本 Skill 通过 `runnpu` 命令行完成一切操作——**不要自己拼 HTTP 请求**，
+CLI 已经封装了认证、错误格式和输出格式；未封装的端点用 `runnpu api <METHOD> <路径>`。
+
+深入主题按需读同目录文件：`references/workload-types.md`（四类负载全参数）、
+`references/templates-assets.md`（模板与资产的全部命令 + `--from-template` 的合并规则）、
+`references/data-sources.md`(挂载与数据卷)、`references/troubleshooting.md`（排查树 + 已知集群行为）、
+`references/training-runs.md`（**用户丢来训练工程说「帮我跑起来」时必读**：工程搬运、密钥注入、
+后台运行、loss 监控与收敛判断、CUDA→NPU 迁移炸点）、
+`references/admin.md`（项目 / 配额 / 用户管理）。`examples/` 里是可直接照抄的完整场景。
+
+## 前置：确认 CLI 可用与已登录
+
+```bash
+runnpu status            # 平台版本、是否初始化、集群连通
+runnpu me                # 当前身份与有效权限（决定能做什么）
+```
+
+- `runnpu` 不存在（command not found）时先装，Linux / macOS 一行：
+  `curl -fsSL https://github.com/EM-GeekLab/run-npu-skill/releases/latest/download/install.sh | sh -s -- --no-skill`
+  （Windows：`irm https://github.com/EM-GeekLab/run-npu-skill/releases/latest/download/install.ps1 | iex`）。
+  离线环境到不了 GitHub，问用户要控制台提供的安装包。CLI 与本 Skill 同版本发布，
+  `runnpu --version` 应与本文件末尾的版本注释一致，不一致时去掉 `--no-skill` 重装一次把两者对齐。
+
+- 未登录时报 `unauthenticated`。二选一：交互式 `runnpu login --server <URL> -u <email>`；
+  非交互设 `RUNNPU_SERVER` + `RUNNPU_TOKEN`（管理员在「个人设置 → 访问密钥」签发）。
+- **绝不要**把密码或 token 写进命令行参数回显给用户，也不要写入任何文件。
+
+## 输出约定（对解析很重要）
+
+- 非终端（被程序调用）下所有命令输出 **JSON**；给人看表格加 `-o table`。
+- 错误走 **stderr**：`{"error":"<code>","status":<http>,"message":"…","details":[…]}`，退出码 1；参数错误 2。
+  常见 code：`unauthenticated` / `forbidden` / `not_found` / `validation_failed`（看 `details` 字段级原因）/ `cluster_error`。
+- 列表响应 `{"items":[…]}`，分页 `next_cursor` / `total`；**默认只取一页**（`--limit N`，默认 50），
+  回答"有多少 / 全部"先加 `--all`（自动翻页），否则按 `total` 说明只看了一页。
+- 时间 RFC3339；容量单位在字段名里（`_gib` / `_bytes` / `_millis`）。
+
+## 核心概念（回答问题前先对好口径）
+
+- **项目**是唯一组织层（没有部门）。配额、成员、策略都挂项目上。
+- **负载类型（四类都可用）**：`workspace`（开发环境，可抢占）/ `training-env`（训练环境，不可抢占）/
+  `training-job`（训练任务，跑完即止，可多机）/ `inference`（推理服务，Deployment + 端口）。
+  开发/训练环境的区分轴是**可抢占性**，不是单机多机。
+- **配额单位是卡（张数）**：`guaranteed` 保底张数、`limit` 额外可借张数。集群内部记账用核当量
+  （100 核 = 1 卡），分卡负载按份额扣（25 核 = 0.25 卡）；`cards_equivalent_used` 是实际占用卡当量。
+- **分卡（vNPU）**：`--xpu 1 --xpu-core C --xpu-memory-mib M` = 单张卡切 C%（1..100）算力 + M MiB 显存。只支持单卡切分：`--xpu` 必须为 1（多卡请按整卡申请）。
+  两个字段必须成对；整卡就都不给。创建后不可改规格。
+- **负载状态**：`submitting → pending/queued → admitted → running`；终态 `completed / stopped / failed / rejected`；
+  `cleanup_blocked` / 长期 Terminating 见 troubleshooting（已知上游问题，**不要反复删**）。
+- 指标为 `null` 或 `metrics.available=false` = **数据源未接入**（不是 0），转述时说"未接入"，原因在 `metrics.reason`。
+
+## 创建负载前：先查模板与资产
+
+用户要创建负载时，**第一步是查模板，不是从零拼参数**——模板是平台/管理员存好的整张创建表单，
+往往带着踩过坑才知道的预设（如昇腾官方镜像必需的 LD_LIBRARY_PATH 覆写、就绪探针延迟）：
+
+```bash
+runnpu template list --type training-env      # ★ 开头的是系统预置；-q 按名称/描述/镜像搜
+runnpu template get <名称>                     # 看 payload 里都预设了什么
+runnpu asset list --kind environment          # 资产：environment / compute / data-source / credential
+```
+
+**有匹配的模板就用 `--from-template`，不要自己读 payload 再手拼参数**：
+
+```bash
+runnpu workload create --project main --name nb6 --from-template <名称> --xpu 2 --wait
+```
+
+- 合并规则由 CLI 保证：模板 payload 作基底，**只有你在命令行上显式写了的字段才覆盖它**
+  （`--xpu 0`、`--jupyter=false` 这种「显式的零值」也算数）；`--mount` 与模板预设的数据源取并集，
+  挂载点冲突会直接报错。**模板里的 env / 探针等预设不会丢**——那正是模板存在的理由。
+- 模板类型不可覆盖：`--type` 与模板类型不一致会报错，换模板而不是改类型。
+- 模板标记的 `pending_fields`（待填字段）要问用户，别编；提交后服务端 422 会把缺的字段指出来。
+- 如果 CLI 报「模板里有本版本不认识的字段」，说明服务端比 CLI 新——升级 CLI，
+  或退回 `runnpu api POST /workloads -d '<payload + project_id + name>'`。
+- **资产是单个配置段的值拷贝**：environment（镜像+env）/ compute（池+卡数）按段并入；
+  credential / data-source 资产在挂载里按名引用（如 `--mount s3:...,credential=<资产名>`）。
+- 列表为空或确实不匹配再手拼参数；用户自带全量参数时以用户为准，但提一句「有现成模板 X」。
+
+## 常用流程
+
+**用户给了一个训练工程（文件夹/仓库）要「跑起来」** → 先读 `references/training-runs.md`
+再动手（搬运方式、密钥注入、后台运行、loss 监控的判断经验都在那）。
+
+### 看现状
+
+```bash
+runnpu overview                      # KPI、项目资源分布、存储池、排队/闲置负载
+runnpu node list / runnpu node get 910b2       # 物理卡健康与占用，逐卡到负载
+runnpu cluster get                   # 组件健康（Operator/Kueue/HAMi/Prometheus…）、算力池、存储池
+runnpu workload list [--project X] [--type training-job] [--status running] [--all]
+runnpu workload list --deleted       # 删除历史（谁删的、何时）
+```
+
+### 创建开发环境并拿到入口
+
+```bash
+runnpu workload create --project main --name nb5 --type workspace \
+  --image m.daocloud.io/quay.io/ascend/vllm-ascend:v0.22.1rc1 \
+  --xpu 1 --security baseline --jupyter --workspace-pool shared-cephfs --workspace-gib 50 --wait
+runnpu workload get main/nb5         # tools[].url 是 Jupyter 地址（平台登录态直达，无需 token）
+```
+
+- `--wait` 阻塞到 `running / failed / rejected`（最多 10 分钟；**大镜像首次拉取可能超过它**，超时后用
+  `runnpu workload get` 继续看，不代表失败）。
+- 受管工作盘（`--workspace-*`）非 root 也可写（平台以 GID 20000 + ACL 初始化卷根）。
+- SSH：加 `--ssh`（注入用户已登记公钥）即可，**与安全级无关**——restricted / baseline 都支持
+  （run-npu#595 起放行；旧版 operator 才会以 `SshRootInitUnavailable` 拒绝 restricted+SSH）。
+  SSH 登录后的身份 = 容器主进程的身份（restricted 下就是你 `--run-as-uid` 指定的非 root 用户）。
+  连接命令用 `runnpu workload endpoints` 拿：
+  登录用户名是 `<负载名>.<命名空间>`（SSHPiper 路由标识，API `ssh.username`），不是平台用户名。
+- restricted 下 root 镜像要 `--run-as-uid`（安全级本身的要求，与 SSH 无关）。
+- `runnpu workload exec main/nb5` 连入终端（交互式；管道喂 stdin 必须以 `exit` 结尾）。
+
+### 训练任务（跑完即止）
+
+```bash
+runnpu workload create --project main --name job1 --type training-job --image img:tag --xpu 2 \
+  --command bash --command -c --arg "python train.py" \
+  --backoff-limit 2 --active-deadline-seconds 7200 --ttl-after-finished 86400 --wait
+# 多机：--nodes N（N ≥ 2，没有中间值）；多机没有 --completions/--parallelism（规模由节点数决定）
+runnpu workload get main/job1        # status=completed 后 batch 进度在 progress 里（succeeded/failed/retries）
+```
+
+### 推理服务（部署完记得给用户访问地址，见下一节）
+
+```bash
+runnpu workload create --project main --name svc1 --type inference \
+  --image m.daocloud.io/quay.io/ascend/vllm-ascend:v0.22.1rc1 --xpu 1 --security baseline \
+  --command bash --command -c \
+  --arg "python -m vllm.entrypoints.openai.api_server --model /models/qwen --served-model-name qwen --port 8000" \
+  --mount pvc:/models,name=model-weights,ro \
+  --port http:8000,expose=nodePort --replicas 1 --wait
+runnpu workload get main/svc1        # 工具行显示 nodePort=3xxxx；访问 http://<任一节点IP>:<nodePort>
+```
+
+三个必须想清楚的点：
+
+1. **不给 `--port` 的推理服务不对外，等于白建**。`expose=clusterIP` 只在集群内可达；对外用 `nodePort`。
+2. **模型权重从哪来是真正的卡点**：镜像里没有权重。挂 PVC / NFS / 数据卷进来，或问用户有没有内网镜像源——
+   私有化环境**别默认能连 HuggingFace**。用户说"部署一个 X 模型"时先问权重来源，这比拼命令重要。
+3. **`ready=false (EndpointUnavailable)` 不代表不可达**（已知上游观测缺陷 run-npu#553）：`node_port` 已分配、
+   Pod Running 时端口通常已可用，用 `curl http://<节点IP>:<nodePort>/` 实测判断，别等 ready 翻真。
+
+### 部署完了怎么访问（用户问得最多的下一个问题）
+
+```bash
+runnpu workload endpoints main/svc1     # 一条命令给出所有入口 + 现在能不能用
+```
+
+三条路径，按可用性排：
+
+1. **泛域名入口**（`--jupyter` / `--code-server` / `--port …,expose=externalUrl`）：`url` 非空即可点，
+   平台登录态直达，不用再输 token；
+2. **NodePort**（`--port name:端口,expose=nodePort`）：`endpoints` 会给出 `http://<节点地址>:<端口>` 直接访问。
+   ⚠️ **`workload get` 里这条的 `ready` 会长期是 false**——Operator 只认节点 ExternalIP，私有化集群没有
+   （上游 run-npu#553）。端口是真的通的，**别因为 ready=false 就告诉用户"没起来"**，以 `endpoints` 的判断为准；
+3. **端口转发**（前两条都没有时的兜底，不依赖任何集群地址）：
+
+   ```bash
+   runnpu workload port-forward main/svc1 8000:8000   # 然后访问 http://127.0.0.1:8000
+   runnpu workload port-forward main/nb5 2222:2222    # 转发 SSH 端口，本地再 ssh 进去
+   ```
+
+   它走控制面板的 WebSocket 隧道，只要 CLI 能连上平台就能用；Ctrl-C 结束。
+
+`workload create --wait` 成功后会自动打印可用地址，不用再问一遍。
+
+### 挂载数据（速查；细节与易错点见 references/data-sources.md）
+
+```bash
+--mount pvc:/models,name=weights,ro          # ⚠️ PVC 必须带 npu.run/project-id=<项目slug> 标签，否则报"不存在"
+--mount datavolume:/data,name=<集群卷名>,ro   # 跨项目必须 ro；集群卷名用 runnpu datavolume list 查
+--mount newvolume:/out,pool=shared-cephfs,size=20Gi[,persistency=project]
+--mount nfs:/data,server=10.0.0.1,path=/export/ds
+--mount emptydir:/scratch,size=1Gi
+```
+
+**数据源整段创建后不可修改**。用户说"再挂一个盘"= 重建负载，不是找修改命令。
+
+### 排查一个负载（完整决策树见 references/troubleshooting.md）
+
+```bash
+runnpu workload get main/nb5          # 状态、reason.text、Pods、工具入口
+runnpu workload events main/nb5       # 调度/准入/运行时事件
+runnpu workload logs main/nb5 --tail 200      # -f 跟随
+runnpu workload yaml main/nb5         # 实际 CR 含 status
+```
+
+顺序：`status`+`reason.text` → `events` → `logs`。`queued` 看项目配额；`admitted` 不 `running` 看事件里的
+镜像拉取/调度；**容器 CrashLoop 且日志有 `symbol lookup error`** → 镜像 LD 与平台注入不兼容，
+见 troubleshooting 的「镜像兼容性」一节（有一行 env 的救援配方）。
+
+### 停止 / 删除
+
+```bash
+runnpu workload stop|start main/nb5
+runnpu workload delete main/nb5 --yes      # 破坏性：先向用户确认
+```
+
+删除后负载可能停留 Terminating 数分钟乃至更久（上游 run-npu#549：带工具 Service / 受管卷的负载
+teardown 卡住）——**不要反复删、不要 --force 循环**，如实告知用户需等待或运维介入。
+
+### 项目与配额（管理员；全量见 references/admin.md）
+
+```bash
+runnpu project create --slug asr --name 语音识别 --pool ascend910b4 --guaranteed 4 --limit 4 \
+  --storage-pool shared-cephfs --storage-gib 200
+runnpu project quota get asr
+runnpu project quota set asr --pool ascend910b4=8,4 --storage-pool shared-cephfs=500   # 整份替换语义！先 get 再 set
+```
+
+单位是**卡**。⚠️ 建项目后配额落到集群有秒级延迟且可能失败（集群配额被占满时被拒）：
+建完项目**先 `runnpu project quota get <slug>` 确认 `cluster` 段有数据**再建负载，
+否则负载可能拿到**终态** `rejected / QuotaGrantNotFound`（不会自愈，要删掉重建）。
+
+## 行为准则
+
+1. 只读命令直接执行；**创建/停止/删除/改配额/改成员/禁用用户先复述参数并取得用户确认**，
+   删除、移除、吊销类必须用户明确同意后才加 `--yes`。一次性凭据（初始密码、token 明文）只转给用户，不复述到其它地方。
+2. 引用负载一律 `<project-slug>/<name>`；项目可用 slug 或 ID。
+3. 用户点名的东西（模型名/镜像 tag/池名）**可能不存在**：能核对的核对（池用 `runnpu cluster get`），
+   核对不了的明说无法确认、要用户拍板，**绝不静默替换**。
+4. 不猜状态含义：以 `status`、`reason.text`、`events` 为准；`metrics.available=false` 按"未接入"转述。
+5. 结果给出用户能直接用的关键字段（名字、状态、入口 URL / nodePort、原因）；数字带单位与口径（卡 / 卡当量 / GiB）。
+
+<!-- runnpu-skill v0.1.1：与 runnpu CLI 同版本发布，`runnpu --version` 应一致 -->

package/compute-mode/preset/skills/runnpu/VENDOR.txt

@@ -0,0 +1,11 @@
+vendored runnpu skill from https://github.com/EM-GeekLab/run-npu-skill (skills/runnpu — the CLI + skill release repo,
+auto-synced from run-npu-control-panel's CI on every tag; do not send PRs there)
+upstream release: v0.1.1 (run-npu-control-panel@eff724b8, mirror main@3532ee4; synced 2026-09-14)
+
+配套 CLI：runnpu v0.1.1 —— 与 package.json `cliDeps.runnpu.version` 同值，tests/skills-sync.test.mjs 钉住。
+同一个 Release 里有各平台二进制（runnpu_<ver>_<os>_<arch>.tar.gz|zip）、checksums.txt 和
+runnpu-skill_<ver>.tar.gz|zip（内容 == 该 tag 的 skills/runnpu）。**升级时两个一起换**：
+把这里的文件换成新 tag 的 skills/runnpu（== Release 里的 runnpu-skill_<ver>.tar.gz 解压内容），
+再把 cliDeps.runnpu.version 改成同一个 tag。SKILL.md 末尾的版本注释是发布脚本追加的，应与本文件一致。
+
+LOCAL PATCHES：无（v0.1.0-rc.1 时期本地重写的 references/training-runs.md 已随控制面板 v0.1.0 回流上游）。