fix: address installation skill review feedback

Author: OutisLi

README.md

@@ -222,13 +222,12 @@ without directly linking every framework.
 >     --skill deepmd-install -y
 > ```
 >
-> If direct GitHub access fails, use `gh-proxy.com` for a public, read-only
-> clone, then install from the local checkout. Do not send credentials or
-> private repository URLs through the proxy.
+> If direct GitHub access fails, clone the official Gitee mirror and install
+> from the local checkout:
 >
 > ```bash
 > git clone --depth 1 \
->     https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+>     https://gitee.com/deepmodeling/deepmd-kit.git \
 >     deepmd-kit-skill-source
 > npx -y skills add ./deepmd-kit-skill-source/skills \
 >     --skill deepmd-install -y

doc/agent-skills.md

@@ -74,13 +74,12 @@ npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills
     --skill '*' -y
 ```
 
-If direct GitHub access fails, use `gh-proxy.com` for a public, read-only clone
-and install from that checkout. Do not send credentials or private repository
-URLs through the proxy.
+If direct GitHub access fails, clone the official Gitee mirror and install from
+that checkout:
 
 ```bash
 git clone --depth 1 \
-    https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+    https://gitee.com/deepmodeling/deepmd-kit.git \
     deepmd-kit-skill-source
 npx -y skills add ./deepmd-kit-skill-source/skills --skill '*' -y
 ```

doc/install/install-with-agent.md

@@ -40,13 +40,12 @@ npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills
     --skill deepmd-install -y
 ```
 
-If direct GitHub access fails, use `gh-proxy.com` for a public, read-only clone
-and install from the local checkout. Do not send credentials or private
-repository URLs through the proxy.
+If direct GitHub access fails, clone the official Gitee mirror and install from
+the local checkout:
 
 ```bash
 git clone --depth 1 \
-    https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+    https://gitee.com/deepmodeling/deepmd-kit.git \
     deepmd-kit-skill-source
 npx -y skills add ./deepmd-kit-skill-source/skills \
     --skill deepmd-install -y

skills/deepmd-install/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deepmd-install
-description: Install or rebuild DeePMD-kit with conda, pip, dp1s, offline packages, Docker, or a source checkout. Use for CPU, NVIDIA CUDA, or ROCm environments; PyTorch, TensorFlow, JAX, or Paddle backends; the C/C++ interface; and DeePMD-enabled LAMMPS, including Kokkos pair styles for DPA4 and DPA4C.
+description: Install or rebuild DeePMD-kit with conda, pip, dp1s, offline packages, Docker, or a source checkout. Use for CPU, NVIDIA CUDA, or ROCm environments; PyTorch, TensorFlow, JAX, or Paddle backends; backend-enabled C/C++ interfaces; and DeePMD-enabled LAMMPS, including Kokkos pair styles for DPA4 and DPA4C.
 ---
 
 # Install DeePMD-kit
@@ -21,6 +21,10 @@ and verify the requested public interface rather than package presence alone.
 | source LAMMPS Kokkos CUDA                       | PyTorch graph artifacts: `deepmd/kk` for DPA4/SeZM and `dpa4spin/kk` for DPA4C                 |
 | ROCm source, Windows source, LAMMPS plugin mode | Follow the version-matched documentation in the selected checkout                              |
 
+Backend-neutral C/C++ libraries with `ALLOW_NO_BACKEND=ON` are outside the
+automated plan. Follow `doc/install/install-from-source.md` in the selected
+checkout for that layout.
+
 ## Hard rules
 
 1. Resolve the absolute directory containing this `SKILL.md` as `SKILL_ROOT`.
@@ -36,7 +40,8 @@ and verify the requested public interface rather than package presence alone.
    `conda activate` from a previous agent tool call.
 1. Render commands with concrete plan values. Stop if a plan placeholder,
    empty required value, unexpected path, or shell variable not assigned
-   earlier in the same command block remains.
+   earlier in the same command block remains. Keep each plan string in the
+   quoted argument position shown by the selected reference.
 1. Never run `git reset --hard`, `git clean`, recursively remove an install
    prefix, or edit shell rc files as part of this workflow. Use a new build
    directory or versioned install prefix instead.
@@ -106,7 +111,7 @@ cannot leak across calls.
 
 | Gate        | Required evidence                                                                                                                 |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Plan        | `validate_plan.py` exits zero and prints the normalized plan                                                                      |
+| Plan        | `validate_plan.py` exits zero and prints a validation summary                                                                     |
 | Environment | The selected package manager and absolute interpreter target the planned environment                                              |
 | Python      | `verify_python.py` passes for the selected backend and accelerator; source builds also match the expected build variant           |
 | C/C++       | Expected libraries and headers exist, dynamic dependencies resolve, and the build cache records the requested accelerator/backend |

skills/deepmd-install/references/easy-install.md

@@ -22,6 +22,9 @@ Do not mix conda, pip, offline, and `dp1s` installations in one prefix. Reuse
 an environment only when the user selected it and the probe found no conflicting
 DeePMD-kit install.
 
+ROCm installations use the source workflow. Packaged LAMMPS and i-PI support
+TensorFlow, PyTorch, and JAX; do not add either extra to a Paddle environment.
+
 For a new venv, create it first, resolve its absolute interpreter, update the
 plan, and re-run `validate_plan.py` before installing packages:
 
@@ -112,30 +115,43 @@ printf '%s  %s\n' "<sha256>" "<absolute-download-path>" | sha256sum --check -
 bash "<absolute-download-path>"
 ```
 
+For `package.artifact_path`, skip curl and verify the local file directly:
+
+```bash
+printf '%s  %s\n' "<sha256>" "<absolute-artifact-path>" | sha256sum --check -
+bash "<absolute-artifact-path>"
+```
+
 Use `shasum -a 256` on systems without `sha256sum`. When a release is split,
 verify each part before concatenating it into a new file. Never execute an HTML
 error page or an artifact whose checksum is unknown.
 
 ## Docker
 
-Pull the exact image reference from the plan and verify it in a disposable
-container:
+Pull the exact image reference from the plan:
 
 ```bash
 docker pull "<registry/image:tag-or-digest>"
-docker run --rm "<registry/image:tag-or-digest>" dp --version
 ```
 
-For CUDA, bind the physical GPU selected for the smoke test:
+Mount the verifier read-only and invoke the backend and accelerator selected by
+the plan:
 
 ```bash
-docker run --rm --gpus 'device=<physical-index>' \
+docker run --rm \
+    --mount \
+    type=bind,src="<absolute-skill-root>/scripts/verify_python.py",dst=/opt/deepmd-install/verify_python.py,readonly \
     "<registry/image:tag-or-digest>" \
-    python -c "import torch; print(torch.cuda.get_device_name(0))"
+    python /opt/deepmd-install/verify_python.py \
+    --backend "<pytorch|tensorflow|jax|paddle>" \
+    --accelerator "<cpu|cuda>" \
+    --expected-version "<deepmd-version>"
 ```
 
-Add only user-selected volume mounts and working directories. Do not mount a
-home directory or source tree read-write merely for version verification.
+For CUDA, add `--gpus 'device=<physical-index>'` from the plan before the
+read-only mount. Omit `--expected-version` when the plan does not pin one. Add
+only user-selected volume mounts and working directories; never mount a home
+directory or source tree read-write for verification.
 
 ## Verification
 
@@ -144,16 +160,20 @@ Run the backend-aware verifier with the absolute installed interpreter:
 ```bash
 "<absolute-python>" "<absolute-skill-root>/scripts/verify_python.py" \
     --backend "<pytorch|tensorflow|jax|paddle>" \
-    --accelerator "<cpu|cuda|rocm>"
+    --accelerator "<cpu|cuda>" \
+    --expected-version "<deepmd-version>" \
+    --expected-prefix "<absolute-environment-prefix>"
 ```
 
+Omit `--expected-version` when `package.deepmd_version` is null.
+
 For packaged host LAMMPS, resolve the executable and require the conventional
 host pair style:
 
 ```bash
 "<absolute-python>" "<absolute-skill-root>/scripts/verify_lammps.py" \
     --binary "<absolute-lammps-binary>" \
-    --model-family conventional \
+    --model-family "<package.lammps_model_family>" \
     --flavor host
 ```
 

skills/deepmd-install/references/failure-modes.md

@@ -65,6 +65,7 @@ current directory:
 test -f "<absolute-skill-root>/scripts/probe_env.py"
 test -f "<absolute-skill-root>/scripts/verify_python.py"
 test -f "<absolute-skill-root>/scripts/verify_lammps.py"
+test -f "<absolute-skill-root>/scripts/verify_native.py"
 ```
 
 Resolve the directory containing `SKILL.md`; do not search for a same-named
@@ -77,12 +78,27 @@ Use the backend-aware verifier and retain its complete output:
 ```bash
 "<absolute-python>" "<absolute-skill-root>/scripts/verify_python.py" \
     --backend "<backend>" \
-    --accelerator "<accelerator>"
+    --accelerator "<accelerator>" \
+    --expected-version "<deepmd-version>" \
+    --expected-prefix "<absolute-environment-prefix>"
 ```
 
+Omit `--expected-version` when the plan does not pin a release.
+
 Check visibility masks from the probe before replacing packages. A false GPU
 availability result may come from `CUDA_VISIBLE_DEVICES`,
 `HIP_VISIBLE_DEVICES`, a driver/runtime mismatch, or a CPU backend package.
+For a ROCm smoke test, inspect occupancy with `rocm-smi`, then bind the planned
+physical index in the same command:
+
+```bash
+HIP_VISIBLE_DEVICES="<physical-index>" \
+    ROCR_VISIBLE_DEVICES="<physical-index>" \
+    "<absolute-python>" "<absolute-skill-root>/scripts/verify_python.py" \
+    --backend "<backend>" \
+    --accelerator rocm \
+    --expected-prefix "<absolute-environment-prefix>"
+```
 
 ## Wrong compiled variant
 
@@ -153,7 +169,10 @@ git -C "<absolute-source-directory>" rev-parse HEAD
 ```
 
 Use a separate clone when `HEAD`, remote, or local changes do not match the
-plan. Do not reset, clean, or rewrite the existing checkout.
+plan. Store the resolved SHA in `source.commit`, revalidate with
+`--require-resolved-source`, and pass the same SHA to
+`verify_python.py --expected-source-commit`. Do not reset, clean, or rewrite
+the existing checkout.
 
 ## Stale build directory
 
@@ -181,7 +200,7 @@ from pathlib import Path
 import torch
 
 print(Path(torch.__file__).resolve().parent / "lib")
-spec = find_spec("nvidia.nccl")
+spec = find_spec("nvidia.nccl") if find_spec("nvidia") is not None else None
 if spec is not None:
     for root in spec.submodule_search_locations or ():
         candidate = Path(root) / "lib"
@@ -277,3 +296,6 @@ printf '%s  %s\n' "<sha256>" "<absolute-download-path>" | sha256sum --check -
 An HTML response, truncated split archive, unexpected top-level directory, or
 checksum mismatch requires a fresh artifact from the planned URL; it is not a
 reason to disable verification.
+
+For `package.artifact_path`, skip curl and run the same file-type and checksum
+checks directly on the absolute local path.

skills/deepmd-install/references/plan-schema.md

@@ -82,8 +82,10 @@ Use `null` for an inapplicable object. Do not add undeclared keys.
   "install_lammps": false,
   "install_ipi": false,
   "artifact_url": null,
+  "artifact_path": null,
   "sha256": null,
-  "docker_image": null
+  "docker_image": null,
+  "lammps_model_family": null
 }
 ```
 
@@ -92,8 +94,11 @@ Use `null` for an inapplicable object. Do not add undeclared keys.
 - Keep the two DeePMD-kit index fields null for the default package index.
   Record a user-selected mirror or the documented pre-release index explicitly.
 - Keep `backend_index_url` null when the default package index is intended.
-- Require `artifact_url` and `sha256` for `offline`.
+- Package indexes and download URLs use HTTPS.
+- Require exactly one of HTTPS `artifact_url` or absolute `artifact_path`, plus
+  `sha256`, for `offline`.
 - Require an immutable image reference or user-selected tag for `docker`.
+- Require `lammps_model_family` for packaged LAMMPS verification.
 
 ### `source`
 
@@ -102,12 +107,14 @@ Use `null` for an inapplicable object. Do not add undeclared keys.
   "directory": "/absolute/path/to/deepmd-kit",
   "remote": "https://github.com/deepmodeling/deepmd-kit.git",
   "ref": "master",
+  "commit": null,
   "editable": false
 }
 ```
 
-Treat `ref` as an opaque Git ref. Resolve it to a commit and record that commit
-in the completion report. Do not reset or clean an existing checkout.
+Treat `ref` as an opaque Git ref. Resolve it to a commit, store the SHA in
+`commit`, and revalidate the plan before building. Do not reset or clean an
+existing checkout.
 
 ### `build`
 
@@ -178,9 +185,9 @@ For a JAX C++ backend, provide either `tensorflow_root` or
 }
 ```
 
-Require a physical GPU index for a CUDA smoke test. Keep `gpu` null for CPU.
-The example path must belong to the selected source checkout or be explicitly
-provided by the user.
+Require a physical GPU index for CUDA and ROCm smoke tests. Keep `gpu` null for
+CPU. The example path must belong to the selected source checkout or be
+explicitly provided by the user.
 
 ## Validation rules
 
@@ -192,8 +199,11 @@ The validator enforces these invariants:
    and a CUDA build.
 1. DPA4C maps to `dpa4spin`/`dpa4spin/kk`; other families map to
    `deepmd`/`deepmd/kk`.
-1. Source directories, build directories, and install prefixes are distinct.
+1. DeePMD, C/C++, and LAMMPS source/build/install paths are distinct.
 1. Checksums contain exactly 64 hexadecimal characters.
+1. Easy-install methods reject ROCm and Paddle packaged LAMMPS/i-PI.
+1. Embedded placeholders, control characters, and POSIX-template escape
+   characters fail before command rendering.
 1. Unknown keys and unsupported combinations fail before any state change.
 
 ## Examples
@@ -224,8 +234,10 @@ The validator enforces these invariants:
     "install_lammps": false,
     "install_ipi": false,
     "artifact_url": null,
+    "artifact_path": null,
     "sha256": null,
-    "docker_image": null
+    "docker_image": null,
+    "lammps_model_family": null
   },
   "source": null,
   "build": null,
@@ -265,13 +277,16 @@ The validator enforces these invariants:
     "install_lammps": false,
     "install_ipi": false,
     "artifact_url": null,
+    "artifact_path": null,
     "sha256": null,
-    "docker_image": null
+    "docker_image": null,
+    "lammps_model_family": null
   },
   "source": {
     "directory": "/work/deepmd-kit",
     "remote": "https://github.com/deepmodeling/deepmd-kit.git",
     "ref": "master",
+    "commit": null,
     "editable": false
   },
   "build": {

skills/deepmd-install/references/source-cpp.md

@@ -5,6 +5,10 @@ Build the C/C++ interface only after the Python/backend gate passes. Use
 CMake options supported by that ref. The published documentation is
 <https://docs.deepmodeling.com/projects/deepmd/en/latest/install/install-from-source.html>.
 
+This workflow builds a backend-enabled C/C++ interface. For backend-neutral
+`libdeepmd_cc`/`libdeepmd_c`, follow the checkout documentation and its explicit
+`ALLOW_NO_BACKEND=ON` contract.
+
 ## Contents
 
 - [Build-directory gate](#build-directory-gate)
@@ -131,9 +135,9 @@ Use the platform library suffix on macOS or Windows. On Linux, fail if any
 installed DeePMD library has an unresolved dynamic dependency:
 
 ```bash
-for library in "<absolute-prefix>"/lib/libdeepmd*.so; do
-    ldd "$library"
-done
+"<absolute-python>" "<absolute-skill-root>/scripts/verify_native.py" \
+    --directory "<absolute-prefix>/lib" \
+    --pattern 'libdeepmd*.so*'
 ```
 
 Finally compile and run a public C++ API probe inside the build directory:

skills/deepmd-install/references/source-lammps.md

@@ -135,7 +135,7 @@ from pathlib import Path
 import torch
 
 paths = [Path(torch.__file__).resolve().parent / "lib"]
-spec = find_spec("nvidia.nccl")
+spec = find_spec("nvidia.nccl") if find_spec("nvidia") is not None else None
 if spec is not None:
     for root in spec.submodule_search_locations or ():
         candidate = Path(root) / "lib"

skills/deepmd-install/references/source-python.md

@@ -28,6 +28,10 @@ git -C "<absolute-source-directory>" checkout --detach \
 git -C "<absolute-source-directory>" rev-parse HEAD
 ```
 
+Store the resolved SHA in `source.commit` and re-run `validate_plan.py` with
+`--require-resolved-source` before installing backend packages or building
+DeePMD-kit.
+
 For an existing checkout, inspect it without changing its branch, remotes, or
 working tree:
 
@@ -177,9 +181,12 @@ cd "<absolute-neutral-directory>" &&
 "<absolute-python>" "<absolute-skill-root>/scripts/verify_python.py" \
     --backend "<pytorch|tensorflow|jax|paddle>" \
     --accelerator "<cpu|cuda|rocm>" \
+    --expected-prefix "<absolute-environment-prefix>" \
+    --expected-source-commit "<resolved-source-commit>" \
     --expected-build-variant "<cpu|cuda|rocm>"
 ```
 
-Add `--expect-custom-op` for a PyTorch source build. Add `--expect-nv` and
-`--expect-vesin` only when their platform markers and the plan require them.
-Do not continue to the C/C++ gate until every requested check passes.
+Add `--expected-version "<deepmd-version>"` when the plan pins a release. Add
+`--expect-custom-op` for a PyTorch source build. Add `--expect-nv` and
+`--expect-vesin` only when their platform markers and the plan require them. Do
+not continue to the C/C++ gate until every requested check passes.