fix: align installation skill plan contracts

Author: OutisLi

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

@@ -73,6 +73,17 @@ non-null.
 
 Use the absolute manager and environment name from the plan. Install only the
 requested packages; do not add LAMMPS, Horovod, or MPI unless they are in scope.
+Treat `package.channels` as authoritative when it is non-empty and preserve its
+order by rendering one `-c` option per entry. This includes selected mirrors and
+pre-release channels such as `conda-forge/label/deepmd-kit_dev` or
+`conda-forge/label/deepmd-kit_rc`. Use `conda-forge` only when the list is empty.
+
+```bash
+"<absolute-conda-or-mamba>" create -n "<environment-name>" \
+    -c "<channel-1>" -c "<channel-2>" deepmd-kit
+```
+
+For an empty `package.channels` list, render the stable default explicitly:
 
 ```bash
 "<absolute-conda-or-mamba>" create -n "<environment-name>" \

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

@@ -62,6 +62,12 @@ validate it, and render the gate again. A command containing an unassigned
 plan variable, an empty required argument, or `<placeholder>` is not
 executable.
 
+For conda, compare every rendered `-c` argument with `package.channels`. An
+empty list uses only the stable `conda-forge` default; a non-empty list replaces
+that default and preserves the recorded order. For JAX C/C++, two null
+TensorFlow roots select the Python-library route. A single root selects its
+corresponding external library route; setting both is ambiguous and invalid.
+
 ## Wrong skill root
 
 Helper scripts belong to the installed skill, not the DeePMD-kit checkout or

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

@@ -94,6 +94,9 @@ 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.
+- For conda, an empty `channels` list selects the stable `conda-forge`
+  default. A non-empty list is authoritative and is rendered in order, with
+  one `-c` option per channel. Keep this list empty for other methods.
 - Package indexes and download URLs use HTTPS.
 - Require exactly one of HTTPS `artifact_url` or absolute `artifact_path`, plus
   `sha256`, for `offline`.
@@ -149,8 +152,16 @@ entirely by its Python package. Require `cuda_home` for a CUDA build and
 Use a dedicated install prefix. Never choose `/`, a home directory, a conda
 prefix, `/usr`, `/usr/local`, or `$HOME/.local` as a disposable prefix.
 
-For a JAX C++ backend, provide either `tensorflow_root` or
-`tensorflow_c_root`. For Paddle C++, provide `paddle_inference_dir`.
+For a JAX C++ backend, the TensorFlow dependency is selected by the two
+nullable roots:
+
+- Keep both null to use the TensorFlow C++ libraries from the selected Python
+  environment with `USE_TF_PYTHON_LIBS=ON`.
+- Set only `tensorflow_root` to use an external TensorFlow C++ installation.
+- Set only `tensorflow_c_root` to use the TensorFlow C library.
+
+The two TensorFlow roots are mutually exclusive. For Paddle C++, provide
+`paddle_inference_dir`.
 
 ### `lammps`
 

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

@@ -35,15 +35,21 @@ build directory. Never delete or recursively replace the install prefix.
 
 Start with all backends disabled, then enable the selected backend and its
 documented C API dependency. Enabling TensorFlow also enables the JAX C API in
-DeePMD-kit by design.
-
-| Backend                 | Required CMake arguments                                                            |
-| ----------------------- | ----------------------------------------------------------------------------------- |
-| PyTorch                 | `-DENABLE_PYTORCH=ON -DUSE_PT_PYTHON_LIBS=ON` plus the PyTorch CMake prefix         |
-| TensorFlow              | `-DENABLE_TENSORFLOW=ON -DUSE_TF_PYTHON_LIBS=ON` and the selected Python executable |
-| JAX with TensorFlow C++ | `-DENABLE_TENSORFLOW=ON -DUSE_TF_PYTHON_LIBS=ON`                                    |
-| JAX with TensorFlow C   | `-DENABLE_JAX=ON -DCMAKE_PREFIX_PATH=<tensorflow-c-root>`                           |
-| Paddle                  | `-DENABLE_PADDLE=ON -DPADDLE_INFERENCE_DIR=<paddle-inference-dir>`                  |
+DeePMD-kit by design. For JAX, select exactly one route from the state of the
+nullable roots in the plan.
+
+| Backend dependency                       | Plan state                      | Required CMake arguments                                                              |
+| ---------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
+| PyTorch                                  | Not applicable                  | `-DENABLE_PYTORCH=ON -DUSE_PT_PYTHON_LIBS=ON` plus the PyTorch CMake prefix           |
+| TensorFlow                               | Not applicable                  | `-DENABLE_TENSORFLOW=ON -DUSE_TF_PYTHON_LIBS=ON` and the selected Python executable   |
+| JAX with Python TensorFlow C++ libraries | Both TensorFlow roots are null  | `-DENABLE_TENSORFLOW=ON -DUSE_TF_PYTHON_LIBS=ON` and the selected Python executable   |
+| JAX with external TensorFlow C++         | Only `tensorflow_root` is set   | `-DENABLE_TENSORFLOW=ON -DUSE_TF_PYTHON_LIBS=OFF -DTENSORFLOW_ROOT=<tensorflow-root>` |
+| JAX with TensorFlow C                    | Only `tensorflow_c_root` is set | `-DENABLE_JAX=ON -DCMAKE_PREFIX_PATH=<tensorflow-c-root>`                             |
+| Paddle                                   | Not applicable                  | `-DENABLE_PADDLE=ON -DPADDLE_INFERENCE_DIR=<paddle-inference-dir>`                    |
+
+The Python TensorFlow C++ route requires the planned interpreter to import a
+TensorFlow package that provides `libtensorflow_cc`. Record and install that
+package during the Python gate before configuring CMake.
 
 For PyTorch, discover the prefix from the planned interpreter in the same shell
 call that configures CMake:

skills/deepmd-install/scripts/validate_plan.py

@@ -245,6 +245,9 @@ def _validate_package(
     for key in ("backend_packages", "channels"):
         if key in package:
             _validate_string_list(package[key], f"package.{key}", errors)
+    channels = package.get("channels")
+    if method != "conda" and isinstance(channels, list) and channels:
+        errors.append("package.channels: non-empty channels require method 'conda'")
     for key in ("install_lammps", "install_ipi"):
         if key in package and not isinstance(package[key], bool):
             errors.append(f"package.{key}: expected a boolean")
@@ -376,6 +379,9 @@ def _validate_cpp(
     for key in ("install_prefix", "build_directory"):
         if not _is_absolute_path(cpp.get(key)):
             errors.append(f"cpp.{key}: expected an absolute path")
+    for key in ("tensorflow_root", "tensorflow_c_root", "paddle_inference_dir"):
+        if cpp.get(key) is not None and not _is_absolute_path(cpp.get(key)):
+            errors.append(f"cpp.{key}: expected an absolute path or null")
     if not all(
         _is_absolute_path(cpp.get(key)) for key in ("install_prefix", "build_directory")
     ) or not _is_absolute_path(source.get("directory")):
@@ -397,12 +403,11 @@ def _validate_cpp(
         forbidden.add(_canonical(environment_prefix))
     if prefix in forbidden:
         errors.append("cpp.install_prefix: select a dedicated, non-shared prefix")
-    if backend == "jax" and not (
-        _is_absolute_path(cpp.get("tensorflow_root"))
-        or _is_absolute_path(cpp.get("tensorflow_c_root"))
+    if backend == "jax" and all(
+        cpp.get(key) is not None for key in ("tensorflow_root", "tensorflow_c_root")
     ):
         errors.append(
-            "cpp: JAX requires tensorflow_root or tensorflow_c_root for the C API"
+            "cpp: JAX tensorflow_root and tensorflow_c_root are mutually exclusive"
         )
     if backend == "paddle" and not _is_absolute_path(cpp.get("paddle_inference_dir")):
         errors.append("cpp.paddle_inference_dir: Paddle C++ requires an absolute path")

source/tests/test_deepmd_install_skill.py

@@ -214,12 +214,51 @@ def test_validate_source_tensorflow_cpu_plan() -> None:
     assert PLAN.validate_plan(plan) == []
 
 
+def test_validate_jax_cpp_with_tensorflow_python_libraries() -> None:
+    """Allow JAX C++ to use TensorFlow libraries from the Python environment."""
+    plan = _source_plan()
+    plan["goal"] = "python+cpp"
+    plan["backend"] = "jax"
+    plan["lammps"] = None
+    assert PLAN.validate_plan(plan) == []
+
+
+def test_validate_jax_cpp_rejects_ambiguous_tensorflow_roots() -> None:
+    """Require one unambiguous TensorFlow dependency route for JAX C++."""
+    plan = _source_plan()
+    plan["goal"] = "python+cpp"
+    plan["backend"] = "jax"
+    plan["lammps"] = None
+    cpp = plan["cpp"]
+    assert isinstance(cpp, dict)
+    cpp["tensorflow_root"] = "/opt/tensorflow-cpp"
+    cpp["tensorflow_c_root"] = "/opt/tensorflow-c"
+    errors = PLAN.validate_plan(plan)
+    assert any("mutually exclusive" in error for error in errors)
+
+
 @pytest.mark.parametrize("method", ["pip", "conda", "offline", "docker"])
 def test_validate_easy_install_plans(method: str) -> None:
     """Accept the method-specific fields for each easy-install path."""
     assert PLAN.validate_plan(_easy_plan(method)) == []
 
 
+def test_validate_conda_channels_are_method_specific() -> None:
+    """Accept selected conda channels without ignoring them for other methods."""
+    plan = _easy_plan("conda")
+    package = plan["package"]
+    assert isinstance(package, dict)
+    package["channels"] = ["conda-forge/label/deepmd-kit_rc", "conda-forge"]
+    assert PLAN.validate_plan(plan) == []
+
+    pip_plan = _easy_plan("pip")
+    pip_package = pip_plan["package"]
+    assert isinstance(pip_package, dict)
+    pip_package["channels"] = ["conda-forge"]
+    errors = PLAN.validate_plan(pip_plan)
+    assert "package.channels: non-empty channels require method 'conda'" in errors
+
+
 def test_validate_offline_plan_requires_checksum() -> None:
     """Reject an offline artifact without an integrity value."""
     plan = _easy_plan("offline")
@@ -841,6 +880,16 @@ def test_docker_reference_uses_backend_aware_verifier() -> None:
     assert "readonly" in reference
 
 
+def test_conda_reference_renders_planned_channels() -> None:
+    """Keep selected conda channels authoritative with a stable default."""
+    reference = (
+        REPOSITORY_ROOT / "skills" / "deepmd-install" / "references" / "easy-install.md"
+    ).read_text(encoding="utf-8")
+    assert "package.channels" in reference
+    assert '-c "<channel-1>" -c "<channel-2>"' in reference
+    assert "Use `conda-forge` only when the list is empty" in reference
+
+
 def test_verify_lammps_dpa4c_cli(tmp_path: Path) -> None:
     """Accept the exact DPA4C host and Kokkos pair styles."""
     binary = tmp_path / "lmp_dpa4c"