1panel-toolkit 0.9.0__tar.gz → 0.9.2__tar.gz

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/CHANGELOG.md

@@ -1,5 +1,73 @@
 # 变更记录
 
+## 0.9.2 — 2026-09-20
+
+面板侧做到"够用"就停：**失败时把根因说清楚**，并把"可选"这条边界写进文档。
+
+### deploy 失败不再只有一句 "status=error"
+
+`install_log` 这个字段从 0.1.0 起就在 `DeployResult` 里、渲染逻辑也有，但**从来没有被填过**
+——安装失败时只打印一行状态，日志一个字都没有，等于把排查推回给人。
+
+现在安装没到 `Running` 时会去读那个容器的 `docker logs --tail=120`，复用冒烟测试那套
+lesson 匹配，报告里直接给：
+
+```
+FAIL  deploy/verify
+  安装状态为 error
+  根因提示: L008 宿主机端口已经被占用
+    → 这不是包的缺陷——1Panel 安装时会在表单里提示端口占用并让你换一个…
+  --- 安装日志尾部 ---
+  | ...
+```
+
+缺密钥的情况也会单独标出来（`待填: …（不是包的缺陷，装的时候补上即可）`），
+和冒烟的 `PENDING` 语义一致。`--json` 里多了 `lessons` / `needs_input`。
+
+### 边界写进 README
+
+- 开头声明：**核心路径不需要面板、不需要 SSH、不需要密钥**——`resolve → recipe → gen →
+  check → depth → fix` 全部离线跑；`deploy` / `uninstall` / `remote` / `panel` 是可选附加。
+- 「它不做什么」补一条：不把在线步骤变成必需，并有测试盯着——把配置指向不存在的文件，
+  `gen` / `check` / `form audit` / `depth` 必须照常通过。
+
+面板侧到此为止（够用即停，不再往下延伸）；有需要再动。
+`pytest` 303 passed，`p1 selftest` 10/10。
+
+## 0.9.1 — 2026-09-20
+
+**撤回 0.9.0 的端口自动化，并把边界写进 README。** 用户指出方向偏了。
+
+### 为什么撤
+
+0.9.0 让 `p1 remote smoke` 在不传 `--ports` 时"从实测放行的候选区间里挑一个空闲端口"。
+两个问题：
+
+1. **端口是包的决定，不是服务器的决定。** 表单默认值就是包的立场，冲突该由 1Panel
+   在安装表单里提示、由 Compose 报错。工具为了"跑通"另找一个端口来装，
+   测的已经不是这个包了——这正是这个工具一直在反对的"为了绿灯而改东西"。
+2. **服务器是变化的，而且是多台。** 把"哪些端口放行、哪些端口空闲"写成常量，
+   等于把工具绑死在一台机器上；用户有好几台服务器，端口放行情况各不相同。
+
+现在恢复原来的语义：不传 `--ports` = 用包自己的表单默认端口；`--ports` 是**显式覆盖**，
+不是自动兜底。同时删掉了 `SMOKE_PORT_CANDIDATES` 这类服务器专属常量。
+
+### 保留了有价值的那一半（与服务器无关）
+
+端口被占用时会失败——这本身是对的，但"容器没起来"这种信息太模糊。新增 lesson
+**L008「宿主机端口已经被占用」**：`bind: address already in use` /
+`Ports are not available` / `port is already allocated` 会被识别出来，并直接说明
+"这不是包的缺陷，1Panel 安装时会提示换端口，SSH 冒烟用 `--ports` 指定"。
+这是解释失败、帮你矫正部署，而不是替你改包。
+
+### 边界写进 README
+
+新增「它不做什么」一节：不替你挑宿主端口；不为某一台服务器调优（不预置任何
+服务器专属常量，只根据当场读到的主机事实做事）；不假装知道上游没写的东西；
+不做需要判断的事。方向漂移时先看这一节。
+
+`pytest` 300 passed，`p1 selftest` 10/10。
+
 ## 0.9.0 — 2026-09-20
 
 冒烟测试的最后一道手工步骤：**端口**。

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 1panel-toolkit
-Version: 0.9.0
+Version: 0.9.2
 Summary: Generate, check, fix and runtime-verify 1Panel app packages from a single spec.
 Author: idkan
 License: MIT License
@@ -44,6 +44,11 @@ Description-Content-Type: text/markdown
 它不绑定任何 agent 宿主：CLI 可以独立使用，也可以由 skill 包装后交给 coding
 agent 调用。
 
+**核心路径不需要面板、不需要 SSH、不需要任何密钥**：`resolve` → `recipe` → `gen` →
+`check` → `depth` → `fix` 全部离线跑，输入是仓库地址（或本地检出），输出是一个包。
+`deploy` / `uninstall` / `remote` / `panel` 是**可选的附加能力**，用面板 API key
+帮你检查部署情况、把失败解释清楚——不配也行，核心不依赖它们。
+
 ## 安装
 
 ```bash
@@ -286,8 +291,8 @@ p1 fix <包目录> --check       # 改完立刻重新校验
 
 ```bash
 p1 remote check                                    # 主机事实（内存/磁盘/已用端口/已有本地应用）
-p1 remote smoke <包目录>                            # 完整一轮冒烟（端口自动挑）
-p1 remote smoke <包目录> --ports 10000              # 指定端口（被占用会直接拒绝）
+p1 remote smoke <包目录>                            # 完整一轮冒烟（用包自己的默认端口）
+p1 remote smoke <包目录> --ports 10000              # 显式覆盖宿主端口
 p1 remote smoke <包目录> --env OV_VLM_API_KEY=sk-…  # 用真实密钥覆盖表单默认值
 ```
 
@@ -295,10 +300,9 @@ p1 remote smoke <包目录> --env OV_VLM_API_KEY=sk-…  # 用真实密钥覆盖
 不会碰到你已装的包），按安装表单的默认值渲染 `.env`，`docker compose up -d`，
 然后轮询到"HTTP 有应答"或"healthcheck 明确 healthy"为止，抓日志、清理。
 
-**端口不用你挑**：不传 `--ports` 时它会先读主机事实，从实测放行的候选区间
-（`10000-10004 / 15000 / 15001`）里选第一个空闲端口，并在报告里标注"（自动选择）"；
-传了但被占用的话，在**上传之前**就退出并说清是哪个端口被占了——以前这种情况会以
-"容器没起来"的形式失败，看起来像包的问题。
+不传 `--ports` 时用的是**包自己的表单默认端口**——冒烟要验的就是这个包，不是
+"在这台机器上换个端口能不能跑"。端口被占用时失败信息会点名 `L008`：
+那不是包的缺陷，1Panel 安装时会提示换一个端口，SSH 冒烟用 `--ports` 指定即可。
 
 判定分三类，退出码不同，便于接 CI：
 
@@ -461,3 +465,21 @@ p1 deploy ./out/app --param ... --uninstall  # 5. 走面板 API 正式安装并
 没有官方 Docker 证据就不猜镜像、端口、卷、UID/GID。高风险运行时权限先保留并
 标注风险，不为了扫描器好看而删。云服务器上做运行时验证时只用已确认放行的端口
 段，避免把安全组问题误判成打包问题。
+
+## 它不做什么
+
+这条界线值得写下来，因为它划错时工具会开始骗人：
+
+- **不把在线步骤变成必需。** 面板与 SSH 是可选的辅助；核心（进 GitHub 地址、出包）
+  完全离线可用，已经有一条测试盯着这件事（配置指向不存在的文件时，
+  `gen` / `check` / `form audit` / `depth` 必须照常通过）。
+- **不替你挑宿主端口。** 端口是包自己的决定（表单默认值），冲突由 1Panel 在安装表单里
+  提示、由 Compose 报错。工具不会为了"跑通"而在服务器上另找一个空闲端口来装——
+  那样测的就不是这个包了。`remote smoke --ports` 是**显式覆盖**，不是自动兜底。
+- **不为某一台服务器调优。** 端口区间、安全组放行情况、镜像缓存都随机器和时间变化；
+  工具只根据它当场读到的这台主机的事实做事（`p1 remote check`），不预置任何
+  服务器专属常量。
+- **不假装知道上游没写的东西。** 镜像、容器端口、挂载点没有证据就拒绝生成；
+  应用自己的变量名要么来自证据、要么由你给。
+- **不做需要判断的事。** 哪些字段用户真必须填、标签怎么翻译、要不要接面板依赖，
+  工具列清单、给依据，但不替你决定（`p1 form audit` + `--plan` 就是为这条设计的）。

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/README.md

@@ -10,6 +10,11 @@
 它不绑定任何 agent 宿主：CLI 可以独立使用，也可以由 skill 包装后交给 coding
 agent 调用。
 
+**核心路径不需要面板、不需要 SSH、不需要任何密钥**：`resolve` → `recipe` → `gen` →
+`check` → `depth` → `fix` 全部离线跑，输入是仓库地址（或本地检出），输出是一个包。
+`deploy` / `uninstall` / `remote` / `panel` 是**可选的附加能力**，用面板 API key
+帮你检查部署情况、把失败解释清楚——不配也行，核心不依赖它们。
+
 ## 安装
 
 ```bash
@@ -252,8 +257,8 @@ p1 fix <包目录> --check       # 改完立刻重新校验
 
 ```bash
 p1 remote check                                    # 主机事实（内存/磁盘/已用端口/已有本地应用）
-p1 remote smoke <包目录>                            # 完整一轮冒烟（端口自动挑）
-p1 remote smoke <包目录> --ports 10000              # 指定端口（被占用会直接拒绝）
+p1 remote smoke <包目录>                            # 完整一轮冒烟（用包自己的默认端口）
+p1 remote smoke <包目录> --ports 10000              # 显式覆盖宿主端口
 p1 remote smoke <包目录> --env OV_VLM_API_KEY=sk-…  # 用真实密钥覆盖表单默认值
 ```
 
@@ -261,10 +266,9 @@ p1 remote smoke <包目录> --env OV_VLM_API_KEY=sk-…  # 用真实密钥覆盖
 不会碰到你已装的包），按安装表单的默认值渲染 `.env`，`docker compose up -d`，
 然后轮询到"HTTP 有应答"或"healthcheck 明确 healthy"为止，抓日志、清理。
 
-**端口不用你挑**：不传 `--ports` 时它会先读主机事实，从实测放行的候选区间
-（`10000-10004 / 15000 / 15001`）里选第一个空闲端口，并在报告里标注"（自动选择）"；
-传了但被占用的话，在**上传之前**就退出并说清是哪个端口被占了——以前这种情况会以
-"容器没起来"的形式失败，看起来像包的问题。
+不传 `--ports` 时用的是**包自己的表单默认端口**——冒烟要验的就是这个包，不是
+"在这台机器上换个端口能不能跑"。端口被占用时失败信息会点名 `L008`：
+那不是包的缺陷，1Panel 安装时会提示换一个端口，SSH 冒烟用 `--ports` 指定即可。
 
 判定分三类，退出码不同，便于接 CI：
 
@@ -427,3 +431,21 @@ p1 deploy ./out/app --param ... --uninstall  # 5. 走面板 API 正式安装并
 没有官方 Docker 证据就不猜镜像、端口、卷、UID/GID。高风险运行时权限先保留并
 标注风险，不为了扫描器好看而删。云服务器上做运行时验证时只用已确认放行的端口
 段，避免把安全组问题误判成打包问题。
+
+## 它不做什么
+
+这条界线值得写下来，因为它划错时工具会开始骗人：
+
+- **不把在线步骤变成必需。** 面板与 SSH 是可选的辅助；核心（进 GitHub 地址、出包）
+  完全离线可用，已经有一条测试盯着这件事（配置指向不存在的文件时，
+  `gen` / `check` / `form audit` / `depth` 必须照常通过）。
+- **不替你挑宿主端口。** 端口是包自己的决定（表单默认值），冲突由 1Panel 在安装表单里
+  提示、由 Compose 报错。工具不会为了"跑通"而在服务器上另找一个空闲端口来装——
+  那样测的就不是这个包了。`remote smoke --ports` 是**显式覆盖**，不是自动兜底。
+- **不为某一台服务器调优。** 端口区间、安全组放行情况、镜像缓存都随机器和时间变化；
+  工具只根据它当场读到的这台主机的事实做事（`p1 remote check`），不预置任何
+  服务器专属常量。
+- **不假装知道上游没写的东西。** 镜像、容器端口、挂载点没有证据就拒绝生成；
+  应用自己的变量名要么来自证据、要么由你给。
+- **不做需要判断的事。** 哪些字段用户真必须填、标签怎么翻译、要不要接面板依赖，
+  工具列清单、给依据，但不替你决定（`p1 form audit` + `--plan` 就是为这条设计的）。

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "1panel-toolkit"
-version = "0.9.0"
+version = "0.9.2"
 description = "Generate, check, fix and runtime-verify 1Panel app packages from a single spec."
 readme = "README.md"
 requires-python = ">=3.10"

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/skill/SKILL.md

@@ -111,7 +111,7 @@ Install the CLI first: `uv tool install 1panel-toolkit` (or `pip install
 
    ```bash
    p1 remote check                              # host facts, free ports
-   p1 remote smoke <package-dir>                # port auto-picked; up, probe, logs, tear down
+   p1 remote smoke <package-dir>                # up, probe, logs, tear down
    p1 deploy <package-dir> --param PANEL_APP_PORT_HTTP=10000 --probe --uninstall --cleanup-local
    ```
 

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/src/p1toolkit/__init__.py

@@ -1,3 +1,3 @@
 """1panel-toolkit: one spec in, a verified 1Panel app package out."""
 
-__version__ = "0.9.0"
+__version__ = "0.9.2"

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/src/p1toolkit/cli.py

@@ -420,6 +420,8 @@ def cmd_deploy(args: argparse.Namespace) -> int:
                     "remote_dir": result.remote_dir,
                     "probe": result.probe,
                     "probe_ok": result.probe_ok,
+                    "lessons": [item.get("id") for item in result.lessons],
+                    "needs_input": result.needs_input,
                 },
                 ensure_ascii=False,
                 indent=2,
@@ -718,8 +720,6 @@ def cmd_remote(args: argparse.Namespace) -> int:
                         "detail": result.detail,
                         "containers": result.container_states,
                         "ports": result.published_ports,
-                        "chosen_ports": result.chosen_ports,
-                        "auto_ports": result.auto_ports,
                         "probe": result.probe,
                         "lessons": [item.get("id") for item in result.lessons],
                         "remote_dir": result.remote_dir,
@@ -1025,8 +1025,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--ports",
         action="append",
         help="host port for the Nth PANEL_APP_PORT_* field (repeatable). "
-        "Omit it and the first free candidate is picked on the host; an occupied "
-        "port is refused before anything is uploaded",
+        "Omit it to use the package's own form defaults",
     )
     remote_smoke.add_argument("--timeout", type=int, default=420)
     remote_smoke.add_argument(

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/src/p1toolkit/deploy.py

@@ -25,7 +25,13 @@ from pathlib import Path
 import yaml
 
 from .panel import PanelClient, PanelError
-from .remote import SshTarget, _tarball, probe_host_port
+from .remote import (
+    SshTarget,
+    _tarball,
+    match_lessons,
+    needs_user_input,
+    probe_host_port,
+)
 
 LOCAL_APP_ROOT = "/opt/1panel/resource/apps/local"
 DEFAULT_INSTALL_TIMEOUT = 600
@@ -44,6 +50,8 @@ class DeployResult:
     kept: bool = False
     probe: str = ""
     probe_ok: bool | None = None
+    lessons: list[dict] = field(default_factory=list)
+    needs_input: list[str] = field(default_factory=list)
 
     def render(self) -> str:
         lines = [f"{'PASS' if self.ok else 'FAIL'}  deploy/{self.stage}"]
@@ -63,6 +71,12 @@ class DeployResult:
             lines.append(f"  {'探针' if self.probe_ok else '探针(失败)'}: {self.probe}")
         if self.remote_dir:
             lines.append(f"  远端: {self.remote_dir}")
+        for item in self.needs_input:
+            lines.append(f"  待填: {item}（不是包的缺陷，装的时候补上即可）")
+        for lesson in self.lessons:
+            lines.append(f"  根因提示: {lesson.get('id')} {lesson.get('title')}")
+            if lesson.get("fix"):
+                lines.append(f"    → {lesson['fix']}")
         if not self.ok and self.install_log:
             lines.append("  --- 安装日志尾部 ---")
             for line in self.install_log.strip().splitlines()[-20:]:
@@ -324,6 +338,20 @@ def deploy(
                 probe_detail, probe_ok, _ = probe_host_port(target, port)
                 if not probe_ok:
                     ok = False
+        # A failure that just says "status=error" sends people hunting. Read the
+        # container's own logs and reuse the lesson matcher the smoke test uses.
+        logs = ""
+        if not ok:
+            container = str((record or {}).get("container") or "")
+            if not container:
+                for line in containers:
+                    if " " in line:
+                        container = line.split(" ")[0]
+                        break
+            if container:
+                logs = target.must(
+                    f"docker logs --tail=120 {shlex.quote(container)} 2>&1 || true"
+                )
         result = DeployResult(
             ok=ok,
             stage="verify" if ok else ("probe" if probe_detail else "verify"),
@@ -342,6 +370,9 @@ def deploy(
             remote_dir=remote_dir,
             probe=probe_detail,
             probe_ok=probe_ok,
+            install_log=logs,
+            lessons=match_lessons(logs) if logs else [],
+            needs_input=needs_user_input(logs) if logs else [],
             kept=not ok,
         )
         if uninstall_after and install_id:

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/src/p1toolkit/remote.py

@@ -28,11 +28,6 @@ from .loader import load_version
 from .model import Version
 
 SMOKE_ROOT = "/tmp/p1-smoke"
-
-# Where a smoke test may bind a host port. These are the ports the cloud test
-# host has shown to be open in its security group (see lesson L005); a filtered
-# port makes the probe look like a packaging bug.
-SMOKE_PORT_CANDIDATES = [10000, 10001, 10002, 10003, 10004, 15000, 15001]
 DEFAULT_TIMEOUT = 420
 
 
@@ -208,8 +203,6 @@ class SmokeResult:
     probe: str = ""
     remote_dir: str = ""
     kept: bool = False
-    chosen_ports: list[int] = field(default_factory=list)
-    auto_ports: bool = False
     unverified: list[str] = field(default_factory=list)
     health: list[str] = field(default_factory=list)
     outcome: str = "pass"  # pass | needs-input | fail
@@ -225,11 +218,7 @@ class SmokeResult:
         if self.container_states:
             lines.append("  容器: " + "; ".join(self.container_states))
         if self.published_ports:
-            suffix = "（自动选择）" if self.auto_ports else ""
-            lines.append("  端口: " + ", ".join(self.published_ports) + suffix)
-        elif self.chosen_ports:
-            suffix = "（自动选择）" if self.auto_ports else ""
-            lines.append("  端口: " + ", ".join(str(p) for p in self.chosen_ports) + suffix)
+            lines.append("  端口: " + ", ".join(self.published_ports))
         if self.probe:
             lines.append(f"  探针: {self.probe}")
         if self.health:
@@ -260,6 +249,10 @@ LOG_SIGNATURES = (
     ("Permission denied", "L004"),
     ("connection refused", "L002"),
     ("Connection refused", "L002"),
+    # A busy host port is not a package defect: the panel offers another one.
+    ("address already in use", "L008"),
+    ("Ports are not available", "L008"),
+    ("port is already allocated", "L008"),
 )
 
 
@@ -338,29 +331,10 @@ def smoke(
     container_name = f"{app_key}-smoke"
     overrides = dict(overrides or {})
     fields = port_fields(version)
-    requested = [int(value) for value in (ports or [])]
-    chosen: list[int] = []
-    # Picking the host port is a decision the toolkit can make for you: the
-    # candidates are the ports the security group has been shown to allow, and
-    # `ss -lnt` says which are free right now.
-    if fields:
-        facts = check_host(target)
-        if requested:
-            busy = [port for port in requested if port in facts.used_ports]
-            if busy:
-                raise RemoteError(
-                    f"端口 {busy} 在 {target.host} 上已被占用；"
-                    "`p1 remote check` 会列出空闲候选，或换一组 --ports"
-                )
-            chosen = requested
-        else:
-            chosen = facts.free(SMOKE_PORT_CANDIDATES)[: len(fields)]
-            if len(chosen) < len(fields):
-                raise RemoteError(
-                    f"主机上没有足够的空闲候选端口（需要 {len(fields)} 个，"
-                    f"候选 {SMOKE_PORT_CANDIDATES}）；用 --ports 指定"
-                )
-    for index, value in enumerate(chosen):
+    # The port is the package's own decision: `--ports` overrides the install
+    # form's default, and without it the smoke run uses exactly what the package
+    # ships. Inventing a free port here would test a configuration no user gets.
+    for index, value in enumerate(ports or []):
         if index < len(fields):
             overrides[fields[index]] = str(value)
     env_text = render_env(version, overrides, container_name)
@@ -440,8 +414,6 @@ def smoke(
             container_states=states,
             published_ports=published,
             probe=probe,
-            chosen_ports=chosen,
-            auto_ports=bool(fields) and not requested,
             remote_dir=remote_dir,
             kept=keep or not ok,
             unverified=unverified,

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/src/p1toolkit/rules/data/lessons.yaml

@@ -83,3 +83,13 @@ lessons:
     cases:
       - "1Panel v2.2.4：key 与 core.db 的 ApiKey 逐字符一致仍被拒；改为签名后 /api/v2/dashboard/base/os 返回 code 200"
     applies_when: 用面板 API 做任何自动化（安装应用、读容器、抓日志）。
+
+  - id: L008
+    title: 宿主机端口已经被占用
+    detector: none
+    severity: warn
+    symptom: "容器起不来，日志或 compose 输出里是 `bind: address already in use` /
+      `Ports are not available` / `port is already allocated`。"
+    root_cause: 包的表单默认端口在这台机器上已经有人用（面板自身、别的应用、或上一次没清干净的容器）。
+    fix: 这不是包的缺陷——1Panel 安装时会在表单里提示端口占用并让你换一个；SSH 冒烟可以先用 `p1 ports <host> <候选端口>` 看清主机状态，再用 `p1 remote smoke --ports <空闲端口>` 指定。别为了跑通而改包里的默认值。
+    applies_when: 首次冒烟或首次安装时。

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/tests/test_config.py

@@ -1,11 +1,54 @@
 from __future__ import annotations
 
+import json
 from pathlib import Path
 
 import pytest
 
+from p1toolkit import cli
 from p1toolkit import config as config_module
 
+SPEC = {
+    "key": "demo-cfg",
+    "name": "Demo Config",
+    "description": "A demo application used by the tests.",
+    "shortDescEn": "A demo application used by the tests.",
+    "version": "1.0.0",
+    "type": "tool",
+    "tags": ["Tool"],
+    "port": 10000,
+    "services": [
+        {
+            "name": "demo",
+            "image": "nginx:1.27-alpine",
+            "container_port": 8080,
+            "mounts": [{"host": "./data", "target": "/app/data"}],
+        }
+    ],
+}
+
+
+def test_the_package_path_needs_no_panel_and_no_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
+) -> None:
+    """Panel and SSH are an optional aid: GitHub in, package out, no credentials.
+
+    Point the config at a path that does not exist (and holds no key) and walk
+    the core path anyway - gen, check, form audit and depth must all pass.
+    """
+    monkeypatch.setenv("P1_CONFIG", str(tmp_path / "absent.toml"))
+    spec_path = tmp_path / "spec.json"
+    spec_path.write_text(json.dumps(SPEC), encoding="utf-8")
+    out = tmp_path / "out"
+
+    assert cli.main(["gen", str(spec_path), "--out", str(out), "--check"]) == 0
+    capsys.readouterr()
+    package = out / "demo-cfg"
+    assert cli.main(["check", str(package)]) == 0
+    assert cli.main(["form", "audit", str(package)]) == 0
+    assert cli.main(["depth", str(package)]) == 0
+    assert "判定：" in capsys.readouterr().out
+
 
 def test_mask_hides_secret_values() -> None:
     masked = config_module.mask("panel.api_key", "DLqcLYuuQzTUGPn2Yjnjlmm3z9nzHn7w")

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/tests/test_deploy.py

@@ -268,3 +268,77 @@ def test_cli_probe_flag_is_optional_valued() -> None:
     assert parser.parse_args(["deploy", "pkg", "--probe"]).probe == "auto"
     assert parser.parse_args(["deploy", "pkg", "--probe", "15000"]).probe == "15000"
     assert parser.parse_args(["deploy", "pkg"]).probe is None
+
+
+# --------------------------------------------------------------------------
+# a failed install explains itself
+# --------------------------------------------------------------------------
+
+
+class _FailingPanel(_FakePanel):
+    def request(self, path, method="GET", payload=None, timeout=None):
+        if path == "/apps/installed/search":
+            self.calls.append((path, method, payload))
+            return {
+                "items": [
+                    {
+                        "id": 77,
+                        "name": "demo",
+                        "status": "error",
+                        "container": "1Panel-localdemo-FAIL",
+                    }
+                ]
+            }
+        return super().request(path, method, payload, timeout)
+
+
+class _LogSsh:
+    def __init__(self, logs: str) -> None:
+        self.logs = logs
+        self.commands: list[str] = []
+
+    def must(self, command: str, timeout: int | None = None) -> str:
+        self.commands.append(command)
+        return self.logs if "docker logs" in command else ""
+
+    def run(self, command, input_bytes=None, timeout=None):
+        self.commands.append(command)
+        return 0, "", ""
+
+
+def _deploy_with_logs(tmp_path: Path, monkeypatch, logs: str):
+    from p1toolkit import deploy as deploy_module
+
+    package = _package(tmp_path)
+    ssh = _LogSsh(logs)
+    monkeypatch.setattr(deploy_module, "upload", lambda t, r, k: f"/remote/{k}")
+    monkeypatch.setattr(deploy_module.time, "sleep", lambda _: None)
+    result = deploy_module.deploy(ssh, _FailingPanel(), package, name="demo", timeout=1)
+    return result, ssh
+
+
+def test_a_failed_install_reports_the_root_cause_lesson(tmp_path: Path, monkeypatch) -> None:
+    result, ssh = _deploy_with_logs(
+        tmp_path,
+        monkeypatch,
+        "Error response from daemon: bind: address already in use",
+    )
+    assert not result.ok
+    assert [item.get("id") for item in result.lessons] == ["L008"]
+    rendered = result.render()
+    assert "根因提示: L008" in rendered
+    assert "1Panel 安装时会" in rendered
+    assert any("docker logs" in command for command in ssh.commands)
+
+
+def test_a_missing_secret_is_called_out_as_not_a_package_bug(
+    tmp_path: Path, monkeypatch
+) -> None:
+    result, _ = _deploy_with_logs(
+        tmp_path,
+        monkeypatch,
+        "ValueError: Credential 0 (default): requires 'api_key' to be set",
+    )
+    assert not result.ok
+    assert result.needs_input
+    assert "不是包的缺陷" in result.render()

{1panel_toolkit-0.9.0 → 1panel_toolkit-0.9.2}/tests/test_remote.py

@@ -8,13 +8,10 @@ from conftest import write_package
 from p1toolkit.loader import load_version
 from p1toolkit.remote import (
     HostFacts,
-    RemoteError,
     SshTarget,
-    SMOKE_PORT_CANDIDATES,
     _first_http_code,
     _probe,
     needs_user_input,
-    smoke,
     _unverifiable,
     _tarball,
     check_host,
@@ -59,6 +56,19 @@ def test_match_lessons_maps_log_signatures() -> None:
     assert match_lessons("all good") == []
 
 
+def test_a_busy_host_port_is_explained_not_treated_as_a_package_bug() -> None:
+    """The panel offers another port; the package's default is not the problem."""
+    logs = (
+        'Error response from daemon: driver failed programming external '
+        'connectivity on endpoint demo: bind: address already in use'
+    )
+    hits = match_lessons(logs)
+    assert [item["id"] for item in hits] == ["L008"]
+    lesson = hits[0]
+    assert "端口" in lesson["title"]
+    assert "1Panel 安装时会在表单里提示" in lesson["fix"]
+
+
 def test_missing_credentials_are_not_a_package_bug() -> None:
     logs = (
         "Invalid value for 'vlm': Value error, Credential 0 (default): "
@@ -162,85 +172,6 @@ class _FakeTarget(SshTarget):
         return self.output
 
 
-class _SmokeTarget(SshTarget):
-    """Answers host facts and the upload/probe commands a smoke run issues."""
-
-    def __init__(self, used_ports: list[int]) -> None:
-        super().__init__(host="fake")
-        self.used = used_ports
-        self.commands: list[str] = []
-        self.uploaded_env = ""
-
-    def must(self, command: str, timeout: float | None = None) -> str:
-        self.commands.append(command)
-        if "hostname:" in command:  # the HOST_SCRIPT
-            return "\n".join(
-                [
-                    "hostname:iZfake",
-                    "os:Ubuntu 24.04",
-                    "docker:29.5.1 / v5.1.3",
-                    "mem:853 1613",
-                    "disk:30",
-                    "cpus:2",
-                    "ports:" + ",".join(str(port) for port in self.used),
-                    "apps:",
-                ]
-            )
-        if "curl" in command:
-            return "200 rc=0"
-        return "OPEN"
-
-    def run(self, command, input_bytes=None, timeout=None):
-        self.commands.append(command)
-        if command.startswith("cat > ") and input_bytes:
-            self.uploaded_env = input_bytes.decode("utf-8")
-        if "docker compose ps" in command or "compose ps" in command:
-            return 0, "demo-smoke|running|running|0.0.0.0:10000->80/tcp", ""
-        return 0, "", ""
-
-
-def _smoke_package(tmp_path: Path) -> Path:
-    return write_package(tmp_path / "demo", key="demo")
-
-
-def test_smoke_picks_a_free_candidate_when_ports_are_omitted(tmp_path: Path) -> None:
-    package = _smoke_package(tmp_path)
-    target = _SmokeTarget(used_ports=[10000, 10001])
-    result = smoke(target, package, timeout=5, ready_timeout=1)
-    assert result.chosen_ports == [10002, 10003, 10004][:1]
-    assert result.auto_ports is True
-    assert "PANEL_APP_PORT_HTTP=10002" in target.uploaded_env
-    assert "（自动选择）" in result.render()
-
-
-def test_smoke_refuses_a_port_that_is_already_taken(tmp_path: Path) -> None:
-    package = _smoke_package(tmp_path)
-    target = _SmokeTarget(used_ports=[10000])
-    with pytest.raises(RemoteError) as excinfo:
-        smoke(target, package, ports=[10000], timeout=5, ready_timeout=1)
-    message = str(excinfo.value)
-    assert "10000" in message and "已被占用" in message
-    # Nothing was uploaded: the check happens before the round trip.
-    assert target.uploaded_env == ""
-
-
-def test_smoke_keeps_the_ports_you_chose(tmp_path: Path) -> None:
-    package = _smoke_package(tmp_path)
-    target = _SmokeTarget(used_ports=[10000])
-    result = smoke(target, package, ports=[15000], timeout=5, ready_timeout=1)
-    assert result.chosen_ports == [15000]
-    assert result.auto_ports is False
-    assert "PANEL_APP_PORT_HTTP=15000" in target.uploaded_env
-
-
-def test_smoke_reports_a_host_without_free_candidates(tmp_path: Path) -> None:
-    package = _smoke_package(tmp_path)
-    target = _SmokeTarget(used_ports=list(SMOKE_PORT_CANDIDATES))
-    with pytest.raises(RemoteError) as excinfo:
-        smoke(target, package, timeout=5, ready_timeout=1)
-    assert "空闲候选端口" in str(excinfo.value)
-
-
 def test_check_host_parses_the_report() -> None:
     output = "\n".join(
         [