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

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

@@ -1,5 +1,85 @@
 # 变更记录
 
+## 0.5.0 — 2026-09-20
+
+配方（recipes）：把"一类应用的成套写法"变成一条命令。
+
+### 配方是什么，不是什么
+
+配方只填空的那部分是**结构**——面板变量到应用变量怎么映射、选择器什么形状、
+哪些变量必须由包自己声明。应用侧的变量名永远来自 `p1 resolve` 的
+`dependency_hints` 或显式的 `--bind`，配方不发明变量名，也不替人决定要不要接依赖。
+
+```bash
+p1 resolve <仓库> --out ./out/app                       # 1. 上游证据 + D10 线索
+p1 recipe apply panel-postgres ./out/app/draft-spec.json --write   # 2. 一键接线
+p1 gen ./out/app/draft-spec.json --check                # 3. 生成 + 校验
+```
+
+- `p1 recipe list` / `p1 recipe show <id>`：三条配方——`panel-postgres`（PostgreSQL /
+  MySQL / MariaDB，两步式选择器）、`panel-redis`、`panel-db-and-cache`（复用前两条，
+  角色表只有一份）。数据在 `rules/data/recipes.yaml`。
+- `p1 recipe apply <id> <spec>` 默认只预览，`--write` 写回 spec；`--bind <角色>=<变量>`
+  补上 hints 没覆盖的角色，`--service <名字>` 指定接到哪个服务上。
+- `require: [host|url]` 表示"二选一即可"：一个连接串本身就带了主机、端口、库名和凭据，
+  这时不该再要求单独的 HOST。
+- 重复 apply 不会产生重复依赖（同 kind 的旧接线被替换）。
+
+### 顺带修掉的 hints 陷阱
+
+原来 `dependency_hints.keys` 把所有 URL 混在一个 `url` 角色里，于是
+`REDIS_URL` 会被 `panel-postgres` 绑到 Postgres 的 URL 模板上——包能生成，
+装出来连的是错的库。现在 hints 增加了 `subjects`（按依赖主体分组：
+`postgresql` / `redis` / `generic-db`…），配方只绑同一 family 的变量；
+`DB_HOST` 这类泛型变量留在 `generic-db` 里，同时可供任何 DB 引擎复用。
+线索的 note 也会直接给出该跑哪条配方。
+
+### 验证
+
+- 实测链路：对一个带 `DATABASE_URL` / `DB_HOST` / `REDIS_URL` 的检出跑
+  `resolve` → `recipe apply panel-postgres --write` → `gen --check` → `0 fail`，
+  表单里出现两步式选择器与 `PANEL_DB_*` 字段，compose 里是字面接线。
+- 新增 12 条测试（绑定、跨主体不串味、缺失必需角色、`--bind`、幂等、
+  组合配方、CLI 预览/写回/未知配方、配方生成的包含法校验），`pytest` 277 passed，
+  `p1 selftest` 9/9。
+
+## 0.4.0 — 2026-09-20
+
+多服务包：draft spec 从"只有主服务"变成"compose 里每个服务各一条"。
+
+### 为什么
+
+0.3.1 修了挂载点跨服务错配，但 `image` / `container_port` / `env` 仍然是跨服务聚合的：
+`draft_spec` 取 `images[0]`、`ports[0]`，并把所有服务的环境变量合并成一份。一个
+"应用 + 自带数据库"的 compose 会因此生成**一个** spec service，里面塞着 sidecar 的
+镜像、端口、甚至数据库密码。openviking（openviking + caddy）实测就是这种形态：
+caddy 的 `OV_ACME_EMAIL` 会出现在主服务上，反过来 caddy 只拿到自己的变量。
+
+### 改了什么
+
+- 新增 `analyze.service_facts()`：按服务取出镜像、端口、bind 挂载、环境变量、
+  `depends_on`、运行时字段（security_opt / user / devices …）与 healthcheck。
+- `draft_spec` 为每个服务生成一条 spec（compose 顺序，第一条仍是主服务、拿
+  `PANEL_APP_PORT_HTTP`，其余服务的容器名带后缀）。Dockerfile 里的变量只归主服务，
+  且不会重复落到已经声明过它的服务上；sidecar 的凭据不会被并进应用服务。
+- 多服务时加一条 note：这些服务已按归属写进 draft，如果面板上已有对应应用
+  （postgresql / redis / mysql），考虑改用 `dependencies` 走面板托管（D10）。
+- **healthcheck**：上游的 healthcheck 块（`test` / `interval` / …）会原样带进 spec 和
+  生成的 compose；上游只有"存在 healthcheck"这一事实时，draft 只写一条提示，
+  不再输出 `healthcheck: true`——那不是定义，Docker 会直接解析失败。新增规则
+  **C005** 拦住手写的非映射 healthcheck。
+- 表单字段顺序：端口字段统一排在前面，多服务时不会被另一个服务的变量隔开。
+
+### 实测
+
+- openviking（openviking + caddy）：draft 从 1 条（镜像/端口/挂载/变量全混）变成
+  2 条各自正确——openviking 拿到自己的镜像、1933、`/app/.openviking`、
+  Dockerfile 变量与真实 healthcheck 块；caddy 拿到 `caddy:2`、1934、
+  `./Caddyfile:/etc/caddy/Caddyfile`、`depends_on: [openviking]` 与自己的变量。
+  `p1 gen --check` → `0 fail`。
+- 新增 9 条测试（多服务归属、sidecar 凭据不串味、healthcheck 块 vs 标志、
+  C005、多服务生成），`pytest` 265 passed。
+
 ## 0.3.2 — 2026-09-20
 
 `p1 depth` 的判定阈值校准。用 `p1 fix` 收敛用户自己的四个包时发现的误判。

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 1panel-toolkit
-Version: 0.3.2
+Version: 0.5.0
 Summary: Generate, check, fix and runtime-verify 1Panel app packages from a single spec.
 Author: idkan
 License: MIT License
@@ -87,6 +87,8 @@ p1 remote smoke <包目录> --ports 10000      # 上传→起容器→探针→
 p1 gen examples/demo-spec.json --out ./out --check   # 从 spec 生成包并立即校验
 p1 gen examples/demo-db-spec.json --out ./out --check # 含面板数据库依赖与 init.sh 的示例
 p1 gen ./out/app/draft-spec.json --allow-unresolved  # 明知缺证据也要生成（会记账）
+p1 recipe list                          # 三条"成套写法"：面板 DB / Redis / 两者
+p1 recipe apply panel-postgres ./out/app/draft-spec.json --write  # 一键接线
 p1 deploy ./out/p1-demo --param PANEL_APP_PORT_HTTP=15000   # 走面板 API 正式安装
 p1 fix <包目录> --check                    # 把 check 的结果幂等修掉
 p1 selftest                                # 验收：这个安装能不能用
@@ -105,7 +107,8 @@ p1 selftest                                # 验收：这个安装能不能用
 `values[].label` 必须是纯字符串、bool label 必须加引号。
 
 规则组 `C0xx` 管 compose：顶层 `version:`、image 引号、`${VAR}` 与表单 envKey
-闭合、`createdBy` 标签、端口 envKey 前缀、外部网络、同名服务 DNS 冲突。
+闭合、`createdBy` 标签、端口 envKey 前缀、外部网络、同名服务 DNS 冲突、
+`healthcheck` 必须是映射（`C005`，`healthcheck: true` 会让 Docker 直接解析失败）。
 
 规则组 `H0xx` 管文件卫生：LF/BOM、README store 风格、`.env.sample` 闭合。
 
@@ -175,6 +178,11 @@ README，抽取出端口、挂载点、环境变量、运行用户、额外运
 落进 draft spec——人工确认过的值必须能到达生成器，而不是停在报告里。产出三份文件：
 `decision-report.md`、`draft-spec.json`、`resolve.json`。
 
+**多服务 compose 按服务归属**：compose 里每个服务在 draft spec 里各占一条，镜像、容器端口、
+bind 挂载、环境变量、`depends_on`、运行时字段都只跟着自己的服务走。Dockerfile 里的变量归
+主服务；sidecar（自带的数据库/缓存）的密码不会被并到应用服务上，反过来也一样。多服务时还会给
+一条提示：如果面板上已经有对应的应用，考虑改用 `dependencies` 走面板托管（D10）。
+
 实测：`halo-dev/halo` 的挂载点在 Dockerfile 里没有 `VOLUME`，但 `HALO_WORK_DIR`
 默认值是 `/root/.halo2`；镜像只在 README 里出现——它把两条都标成 `inferred`
 并给出出处，而不是停下来或者瞎猜。
@@ -250,6 +258,9 @@ p1 fix <包目录> --check       # 改完立刻重新校验
 | openviking | 1 fail + 6 warn | **0 fail + 1 warn** | 8 处 |
 | xiaozhi-esp32-server | 1 fail + 13 warn | **0 fail + 1 warn** | 14 处 |
 
+（2026-09-20 在真实包上的实测记录；这些包随后已就地修复，
+`xiaozhi-esp32-server-full` 现在是 `0 fail / 0 warn`。）
+
 静态校验和生成的 YAML 都不能告诉你"容器起不起得来、端口通不通、应用找不找得到配置文件"。
 
 ```bash
@@ -382,6 +393,24 @@ p1 gen ./out/app/draft-spec.json --allow-unresolved
 这两件事同样受证据约束：声明 `user` / `data_owner` 却拿不出 D07 证据、带了依赖而
 D10 说"未检测到"、带了脚本而 D09 无证据——都会在证据审计里被点名（lesson L004）。
 
+### 配方（recipes）：把成套写法变成一条命令
+
+```bash
+p1 resolve <仓库> --out ./out/app                                  # 上游证据 + D10 线索
+p1 recipe apply panel-postgres ./out/app/draft-spec.json --write   # 一键接线
+p1 gen ./out/app/draft-spec.json --check                           # 生成 + 校验
+```
+
+配方只填空的那部分是**结构**：面板变量怎么映射到应用变量、选择器什么形状、哪些变量得由
+包自己声明。应用侧的变量名一律来自 `resolve` 的 `dependency_hints`（或 `--bind` 显式给出），
+配方不发明变量名，也不替人决定要不要接依赖。
+
+三条内置配方：`panel-postgres`（PostgreSQL / MySQL / MariaDB，两步式选择器）、
+`panel-redis`、`panel-db-and-cache`（复用前两条）。`p1 recipe show <id>` 展开角色表；
+`p1 recipe apply` 默认只预览，加 `--write` 写回 spec；`--bind host=DB_HOST` 补 hints 没覆盖的
+角色。hints 的 `subjects` 会区分 `postgresql` 与 `redis` 这类**依赖主体**，所以
+`REDIS_URL` 不会被绑到 Postgres 的连接串模板上。
+
 ## 当前状态
 
 完整流程已经闭环：

{1panel_toolkit-0.3.2 → 1panel_toolkit-0.5.0}/README.md

@@ -53,6 +53,8 @@ p1 remote smoke <包目录> --ports 10000      # 上传→起容器→探针→
 p1 gen examples/demo-spec.json --out ./out --check   # 从 spec 生成包并立即校验
 p1 gen examples/demo-db-spec.json --out ./out --check # 含面板数据库依赖与 init.sh 的示例
 p1 gen ./out/app/draft-spec.json --allow-unresolved  # 明知缺证据也要生成（会记账）
+p1 recipe list                          # 三条"成套写法"：面板 DB / Redis / 两者
+p1 recipe apply panel-postgres ./out/app/draft-spec.json --write  # 一键接线
 p1 deploy ./out/p1-demo --param PANEL_APP_PORT_HTTP=15000   # 走面板 API 正式安装
 p1 fix <包目录> --check                    # 把 check 的结果幂等修掉
 p1 selftest                                # 验收：这个安装能不能用
@@ -71,7 +73,8 @@ p1 selftest                                # 验收：这个安装能不能用
 `values[].label` 必须是纯字符串、bool label 必须加引号。
 
 规则组 `C0xx` 管 compose：顶层 `version:`、image 引号、`${VAR}` 与表单 envKey
-闭合、`createdBy` 标签、端口 envKey 前缀、外部网络、同名服务 DNS 冲突。
+闭合、`createdBy` 标签、端口 envKey 前缀、外部网络、同名服务 DNS 冲突、
+`healthcheck` 必须是映射（`C005`，`healthcheck: true` 会让 Docker 直接解析失败）。
 
 规则组 `H0xx` 管文件卫生：LF/BOM、README store 风格、`.env.sample` 闭合。
 
@@ -141,6 +144,11 @@ README，抽取出端口、挂载点、环境变量、运行用户、额外运
 落进 draft spec——人工确认过的值必须能到达生成器，而不是停在报告里。产出三份文件：
 `decision-report.md`、`draft-spec.json`、`resolve.json`。
 
+**多服务 compose 按服务归属**：compose 里每个服务在 draft spec 里各占一条，镜像、容器端口、
+bind 挂载、环境变量、`depends_on`、运行时字段都只跟着自己的服务走。Dockerfile 里的变量归
+主服务；sidecar（自带的数据库/缓存）的密码不会被并到应用服务上，反过来也一样。多服务时还会给
+一条提示：如果面板上已经有对应的应用，考虑改用 `dependencies` 走面板托管（D10）。
+
 实测：`halo-dev/halo` 的挂载点在 Dockerfile 里没有 `VOLUME`，但 `HALO_WORK_DIR`
 默认值是 `/root/.halo2`；镜像只在 README 里出现——它把两条都标成 `inferred`
 并给出出处，而不是停下来或者瞎猜。
@@ -216,6 +224,9 @@ p1 fix <包目录> --check       # 改完立刻重新校验
 | openviking | 1 fail + 6 warn | **0 fail + 1 warn** | 8 处 |
 | xiaozhi-esp32-server | 1 fail + 13 warn | **0 fail + 1 warn** | 14 处 |
 
+（2026-09-20 在真实包上的实测记录；这些包随后已就地修复，
+`xiaozhi-esp32-server-full` 现在是 `0 fail / 0 warn`。）
+
 静态校验和生成的 YAML 都不能告诉你"容器起不起得来、端口通不通、应用找不找得到配置文件"。
 
 ```bash
@@ -348,6 +359,24 @@ p1 gen ./out/app/draft-spec.json --allow-unresolved
 这两件事同样受证据约束：声明 `user` / `data_owner` 却拿不出 D07 证据、带了依赖而
 D10 说"未检测到"、带了脚本而 D09 无证据——都会在证据审计里被点名（lesson L004）。
 
+### 配方（recipes）：把成套写法变成一条命令
+
+```bash
+p1 resolve <仓库> --out ./out/app                                  # 上游证据 + D10 线索
+p1 recipe apply panel-postgres ./out/app/draft-spec.json --write   # 一键接线
+p1 gen ./out/app/draft-spec.json --check                           # 生成 + 校验
+```
+
+配方只填空的那部分是**结构**：面板变量怎么映射到应用变量、选择器什么形状、哪些变量得由
+包自己声明。应用侧的变量名一律来自 `resolve` 的 `dependency_hints`（或 `--bind` 显式给出），
+配方不发明变量名，也不替人决定要不要接依赖。
+
+三条内置配方：`panel-postgres`（PostgreSQL / MySQL / MariaDB，两步式选择器）、
+`panel-redis`、`panel-db-and-cache`（复用前两条）。`p1 recipe show <id>` 展开角色表；
+`p1 recipe apply` 默认只预览，加 `--write` 写回 spec；`--bind host=DB_HOST` 补 hints 没覆盖的
+角色。hints 的 `subjects` 会区分 `postgresql` 与 `redis` 这类**依赖主体**，所以
+`REDIS_URL` 不会被绑到 Postgres 的连接串模板上。
+
 ## 当前状态
 
 完整流程已经闭环：

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "1panel-toolkit"
-version = "0.3.2"
+version = "0.5.0"
 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.2 → 1panel_toolkit-0.5.0}/skill/SKILL.md

@@ -85,7 +85,9 @@ Install the CLI first: `uv tool install 1panel-toolkit` (or `pip install
      [{kind, kinds, style, env}]`. The generator renders the selector
      (`type: apps` + `child.type: service` by default) and maps `${PANEL_DB_*}`
      onto the application's own variable names, which *you* supply - it never
-     invents them. `p1 resolve` lists candidates under `dependency_hints`.
+     invents them. `p1 resolve` lists candidates under `dependency_hints`, and
+     `p1 recipe apply panel-postgres <spec> --write` turns those hints into the
+     wiring in one step (`p1 recipe list` for the other recipes).
    * **D09, first-run config and permissions** - `config_files` ships the
      template the container reads, `data_owner` generates `init.sh` /
      `upgrade.sh` that create the mounted directories and hand them to the user

{1panel_toolkit-0.3.2 → 1panel_toolkit-0.5.0}/src/p1toolkit/__init__.py

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

{1panel_toolkit-0.3.2 → 1panel_toolkit-0.5.0}/src/p1toolkit/checks/compose.py

@@ -59,6 +59,7 @@ def run(package: Package, report: Report, strict: bool = False) -> None:
         _check_services(version, report, name, generic)
         _check_ports(version, report, name)
         _check_networks(version, report, name)
+        _check_healthcheck(version, report, name)
 
 
 def _check_images(version: Version, report: Report, name: str, strict: bool) -> None:
@@ -186,3 +187,18 @@ def _check_networks(version: Version, report: Report, name: str) -> None:
             "can be reached through 1Panel's entry",
             name,
         )
+
+
+def _check_healthcheck(version: Version, report: Report, name: str) -> None:
+    """`healthcheck:` must be a mapping; `healthcheck: true` breaks the parse."""
+    for service_name, service in version.services.items():
+        if not isinstance(service, dict) or "healthcheck" not in service:
+            continue
+        healthcheck = service["healthcheck"]
+        if not isinstance(healthcheck, dict):
+            report.fail(
+                "C005",
+                f"service {service_name}: healthcheck 必须是映射（test/interval/…），"
+                f"现在是 {type(healthcheck).__name__}；Docker 解析不过",
+                name,
+            )

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

@@ -31,6 +31,7 @@ from .resolve import resolve as resolve_target
 from .resolve import write_outputs as write_resolve_outputs
 from .remote import RemoteError, SshTarget, check_host, smoke as run_smoke
 from .gen import GenResult, SpecError, generate as generate_package, load_spec
+from . import recipes as recipes_module
 from .deploy import DeployError, deploy as run_deploy, remove_local, uninstall as run_uninstall
 from .selftest import run as run_selftest
 from .fix import fix as run_fix
@@ -494,6 +495,71 @@ def cmd_selftest(args: argparse.Namespace) -> int:
     return 0 if result.ok else 1
 
 
+def cmd_recipe(args: argparse.Namespace) -> int:
+    import json as _json
+
+    if args.action == "list":
+        items = recipes_module.rules.recipes()
+        if args.json:
+            print(_json.dumps(items, ensure_ascii=False, indent=2))
+            return 0
+        width = max((len(str(item["id"])) for item in items), default=10)
+        for item in items:
+            matches = ",".join(item.get("matches") or [])
+            print(f"{item['id']:<{width}}  {item.get('title')}  [{matches}]")
+        return 0
+
+    if args.action == "show":
+        try:
+            print(recipes_module.describe(args.recipe_id))
+        except SpecError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        return 0
+
+    # apply
+    spec_path = Path(args.spec).resolve()
+    if not spec_path.exists():
+        print(f"error: 找不到 spec: {spec_path}", file=sys.stderr)
+        return 2
+    try:
+        spec = load_spec(spec_path)
+        updated, result = recipes_module.apply(
+            args.recipe_id, spec, binds=args.bind, service=args.service or ""
+        )
+    except SpecError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(
+            _json.dumps(
+                {
+                    "recipe": result.recipe.get("id"),
+                    "dependencies": result.dependencies,
+                    "bound": result.bound,
+                    "missing": result.missing,
+                    "warnings": result.warnings,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        print(result.render())
+    if args.write:
+        spec_path.write_text(
+            _json.dumps(updated, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+        print(f"\n已写入 {spec_path}")
+        print("下一步：`p1 gen <spec> --check`")
+    elif not args.json:
+        print("\n（预览；加 --write 写回 spec）")
+    return 0
+
+
 def cmd_fix(args: argparse.Namespace) -> int:
     target = Path(args.path).resolve()
     if not target.is_dir():
@@ -733,6 +799,32 @@ def build_parser() -> argparse.ArgumentParser:
     pat_export.set_defaults(action="export", func=cmd_patterns)
     pat.set_defaults(action="list", func=cmd_patterns)
 
+    recipe = sub.add_parser(
+        "recipe", help="apply a packaged way of wiring panel-managed dependencies"
+    )
+    recipe_sub = recipe.add_subparsers(dest="action")
+    recipe_list = recipe_sub.add_parser("list", help="list recipes")
+    recipe_list.add_argument("--json", action="store_true")
+    recipe_list.set_defaults(action="list", func=cmd_recipe)
+    recipe_show = recipe_sub.add_parser("show", help="explain one recipe")
+    recipe_show.add_argument("recipe_id")
+    recipe_show.set_defaults(action="show", func=cmd_recipe)
+    recipe_apply = recipe_sub.add_parser(
+        "apply", help="merge a recipe's dependency wiring into a spec"
+    )
+    recipe_apply.add_argument("recipe_id")
+    recipe_apply.add_argument("spec", help="spec JSON (a resolve draft works)")
+    recipe_apply.add_argument(
+        "--bind",
+        action="append",
+        help="role=ENV_NAME for a role the hints do not cover, e.g. --bind host=DB_HOST",
+    )
+    recipe_apply.add_argument("--service", help="which spec service to wire (default: the first)")
+    recipe_apply.add_argument("--write", action="store_true", help="write the spec back")
+    recipe_apply.add_argument("--json", action="store_true")
+    recipe_apply.set_defaults(action="apply", func=cmd_recipe)
+    recipe.set_defaults(action="list", func=cmd_recipe)
+
     depth = sub.add_parser(
         "depth", help="measure how app-specific a package is (template vs adapted)"
     )

{1panel_toolkit-0.3.2 → 1panel_toolkit-0.5.0}/src/p1toolkit/gen.py

@@ -208,6 +208,9 @@ def build_fields(
     dependency wiring (which is rendered literally, not as a default).
     """
     fields: list[dict] = []
+    # Ports first: with more than one service the port fields would otherwise be
+    # scattered between another service's variables.
+    port_fields: list[dict] = []
     hidden: dict[str, list[str]] = {}
     # Keys the generator adds on its own; they must not be double counted as
     # "hidden upstream variables" when the upstream compose also sets them.
@@ -219,7 +222,7 @@ def build_fields(
         port = service.get("container_port")
         if port:
             env_key = "PANEL_APP_PORT_HTTP" if port_index == 0 else f"PANEL_APP_PORT_{port_index}"
-            fields.append(
+            port_fields.append(
                 {
                     "envKey": env_key,
                     "type": "number",
@@ -252,6 +255,7 @@ def build_fields(
                 entry["description"] = item["description"]
             fields.append(entry)
 
+    fields = port_fields + fields
     hidden = {
         service: [key for key in keys if key not in reserved]
         for service, keys in hidden.items()
@@ -370,7 +374,6 @@ def build_compose(
         if env_lines:
             entry["environment"] = env_lines
         for extra in (
-            "healthcheck",
             "security_opt",
             "cap_add",
             "cap_drop",
@@ -392,6 +395,16 @@ def build_compose(
         ):
             if service.get(extra):
                 entry[extra] = service[extra]
+        # `healthcheck` is a mapping, never a flag: a boolean from a spec (or an
+        # evidence flag) must not reach the compose file, Docker rejects it.
+        healthcheck = service.get("healthcheck")
+        if isinstance(healthcheck, dict):
+            entry["healthcheck"] = healthcheck
+        elif healthcheck:
+            warnings.append(
+                f"{name}: healthcheck 不是映射（{healthcheck!r}），已忽略；"
+                "探针要写成 {test: [...], interval: 10s, ...}"
+            )
         entry["labels"] = {"createdBy": "Apps"}
         services[name] = entry