1panel-toolkit 0.3.1__tar.gz → 0.3.2__tar.gz

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 变更记录
 
+## 0.3.2 — 2026-09-20
+
+`p1 depth` 的判定阈值校准。用 `p1 fix` 收敛用户自己的四个包时发现的误判。
+
+### 判定：只缺一个维度不再是 thin
+
+原来的 `assess()` 是"三个多样性维度（对外端口 / 持久化挂载 / 应用自有变量）里
+缺任意一个 → thin"。于是 `xiaozhi-esp32-server` 被判成 `thin`——可它有 2 个对外端口、
+2 个挂载点（其中一个还是模型文件 `model.pt`）、`security_opt`、`init.sh`，只是把配置
+全放在挂载的 `data/.config.yaml` 里，本来就不该有应用变量。
+
+现在：**缺两个及以上才算薄**；只缺一个仍是 `adapted`，但会打一条 `·` 说明；
+与不相干官方包重合 ≥ 50% 仍是 `possibly-reskinned`。顺带 `p1 depth <包>`
+不再需要 `--corpus` 也会给判定（只有"最接近的官方包"那节需要语料）。
+
+四个真实包的判定：hindsight `adapted`、openviking `adapted`、
+xiaozhi-esp32-server `adapted`（附一条"没有任何应用自有环境变量"的说明）、
+xiaozhi-esp32-server-full `adapted`。
+
+### 验证
+
+- 新增 2 条测试（缺一个维度 → adapted + note；缺两个 → thin），`pytest` 257 passed。
+- 收敛后的四个包 `p1 check`：hindsight `0 fail, 2 warn`、openviking `0 fail, 1 warn`、
+  xiaozhi-esp32-server `0 fail, 1 warn`、xiaozhi-esp32-server-full `OK  no issues`，
+  与 README 表格一致；`p1 fix` 二次运行四个包都是"没有需要修复的内容"（幂等）。
+
 ## 0.3.1 — 2026-09-20
 
 独立验证（另一个 session 的只读复现）挖出的三个真 bug，外加发布产物卫生。

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 1panel-toolkit
-Version: 0.3.1
+Version: 0.3.2
 Summary: Generate, check, fix and runtime-verify 1Panel app packages from a single spec.
 Author: idkan
 License: MIT License

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/docs/generation-depth.md

@@ -99,7 +99,10 @@ p1 depth <包目录> --corpus <官方apps目录>          # 单个包的判定 +
 判定逻辑基于"应用特有特征指纹"（容器内端口、挂载点、应用变量名、镜像、额外运行时
 字段），做 Jaccard 相似度：
 
-- 缺少端口 / 挂载 / 应用变量 → `thin`
+- 三个"多样性维度"（对外端口 / 持久化挂载 / 应用自有变量）里**缺两个及以上** → `thin`
+- 只缺一个 → 仍是 `adapted`，但会打一条 `·` 说明。应用完全可以把配置放在挂载的
+  配置文件里（xiaozhi 的 `data/.config.yaml`、openviking 的 `ov.conf`），这时
+  "没有应用变量"是设计而不是薄——把这种情况判成 thin 会逼人往 compose 里塞无意义的变量
 - 与某个不相干的包重合度 ≥ 50% → `possibly-reskinned`
 - 都不满足 → `adapted`
 

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "1panel-toolkit"
-version = "0.3.1"
+version = "0.3.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.3.1 → 1panel_toolkit-0.3.2}/src/p1toolkit/__init__.py

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

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/src/p1toolkit/cli.py

@@ -268,11 +268,14 @@ def cmd_depth(args: argparse.Namespace) -> int:
                 print(f"  - {value}")
             if len(values) > 12:
                 print(f"  ... 另外 {len(values) - 12} 项")
+        # The profile-based verdict needs no corpus; only the twin search does.
+        verdict = depth_module.assess(profile, corpus)
+        print(f"\n判定：{verdict.status}")
+        for reason in verdict.reasons:
+            print(f"  ! {reason}")
+        for note in verdict.notes:
+            print(f"  · {note}")
         if corpus:
-            verdict = depth_module.assess(profile, corpus)
-            print(f"\n判定：{verdict.status}")
-            for reason in verdict.reasons:
-                print(f"  ! {reason}")
             print("\n与官方语料最接近的包：")
             found = depth_module.nearest(profile, corpus)
             if not found:

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/src/p1toolkit/depth.py

@@ -366,6 +366,7 @@ class Verdict:
     status: str
     score: float
     reasons: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
     twin: str | None = None
 
     @property
@@ -380,18 +381,28 @@ def assess(
 
     The dimensions that carry all the diversity in the store (container ports,
     mount targets, application variable names) are exactly the ones a template
-    cannot answer. A package with thin values there, or one that is nearly
-    identical to an unrelated app, is probably a reskin.
+    cannot answer. A package missing *one* of them is a judgement call and only
+    gets a note — an app can legitimately carry its configuration in a mounted
+    file instead of environment variables. Missing two or more means the
+    package is a shell; a near-identical unrelated app means it is a reskin.
     """
     reasons: list[str] = []
+    notes: list[str] = []
     if not profile.images:
         reasons.append("compose 里没有可识别的镜像")
-    if not profile.port_pairs:
-        reasons.append("没有对外端口映射")
-    if not profile.mount_targets:
-        reasons.append("没有持久化挂载点（除非这个应用真的无状态）")
-    if not profile.app_env_keys:
-        reasons.append("没有任何应用自有环境变量（多数应用都有配置项）")
+    missing = [
+        text
+        for present, text in (
+            (profile.port_pairs, "没有对外端口映射"),
+            (profile.mount_targets, "没有持久化挂载点（除非这个应用真的无状态）"),
+            (profile.app_env_keys, "没有任何应用自有环境变量（多数应用都有配置项）"),
+        )
+        if not present
+    ]
+    if len(missing) >= 2:
+        reasons.extend(missing)
+    else:
+        notes.extend(missing)
     twin = None
     score = 0.0
     found = nearest(profile, corpus, threshold=twin_threshold, limit=1)
@@ -404,10 +415,16 @@ def assess(
         )
 
     if not reasons:
-        return Verdict(status="adapted", score=score)
+        return Verdict(status="adapted", score=score, notes=notes)
     if twin:
-        return Verdict(status="possibly-reskinned", score=score, reasons=reasons, twin=twin)
-    return Verdict(status="thin", score=score, reasons=reasons)
+        return Verdict(
+            status="possibly-reskinned",
+            score=score,
+            reasons=reasons,
+            notes=notes,
+            twin=twin,
+        )
+    return Verdict(status="thin", score=score, reasons=reasons, notes=notes)
 
 
 def to_json(data: dict[str, Any]) -> str:

{1panel_toolkit-0.3.1 → 1panel_toolkit-0.3.2}/tests/test_depth.py

@@ -64,6 +64,56 @@ def test_adapted_package_passes(tmp_path: Path) -> None:
     assert assess(profile, []).status == "adapted"
 
 
+def test_missing_one_dimension_is_a_note_not_a_verdict(tmp_path: Path) -> None:
+    """An app can carry its config in a mounted file instead of env vars.
+
+    xiaozhi-esp32-server is exactly that shape: two ports, a model-file mount,
+    security_opt, an init script, and zero application variables because
+    everything lives in `data/.config.yaml`. Calling that "thin" is wrong.
+    """
+    compose = (
+        "services:\n"
+        "  app:\n"
+        '    image: "ghcr.io/example/app:1.0"\n'
+        "    container_name: ${CONTAINER_NAME}\n"
+        "    networks:\n"
+        "      - 1panel-network\n"
+        "    ports:\n"
+        '      - "${PANEL_APP_PORT_HTTP}:8000"\n'
+        "    volumes:\n"
+        "      - ./data:/opt/app/data\n"
+        "networks:\n"
+        "  1panel-network:\n"
+        "    external: true\n"
+    )
+    profile = profile_app(write_package(tmp_path / "demo", key="demo", compose=compose))
+    verdict = assess(profile, [])
+    assert verdict.status == "adapted"
+    assert not verdict.reasons
+    assert any("环境变量" in note for note in verdict.notes)
+
+
+def test_two_missing_dimensions_are_still_thin(tmp_path: Path) -> None:
+    compose = (
+        "services:\n"
+        "  app:\n"
+        '    image: "ghcr.io/example/app:1.0"\n'
+        "    container_name: ${CONTAINER_NAME}\n"
+        "    networks:\n"
+        "      - 1panel-network\n"
+        "    ports:\n"
+        '      - "${PANEL_APP_PORT_HTTP}:8000"\n'
+        "networks:\n"
+        "  1panel-network:\n"
+        "    external: true\n"
+    )
+    profile = profile_app(write_package(tmp_path / "demo", key="demo", compose=compose))
+    verdict = assess(profile, [])
+    assert verdict.shallow
+    assert any("挂载" in reason for reason in verdict.reasons)
+    assert any("环境变量" in reason for reason in verdict.reasons)
+
+
 def test_similarity_finds_a_reskin(tmp_path: Path) -> None:
     first = profile_app(write_package(tmp_path / "a", key="a"))
     second = profile_app(write_package(tmp_path / "b", key="b"))
@@ -131,4 +181,3 @@ def test_templateable_dimensions_documented() -> None:
     templatable = data.get("templatable") or []
     assert templatable
     assert any("重启策略" in str(item.get("dimension")) for item in templatable)
-