quadlet-migrator-skill/README.zh-CN.md

Quadlet Migrator

English | 简体中文

一个 skill，用来将 docker run 命令和 Docker Compose 风格部署迁移为可维护的 Podman Quadlet 单元。

功能概览

• 将 docker run 和 Compose 风格输入转换为面向 Quadlet 的设计
• 默认先把生成产物写到当前目录，便于审查后再应用
• 只有在用户已要求其他位置，或现有文件冲突需要决策时，才询问输出位置
• 帮助在 .container、.pod、.network、.volume、.build 之间做选择，并对多容器服务默认偏向 pod-first 拓扑
• 在合适时保留 .env / env_file 工作流
• 将大型 env 模板归纳为少量高影响部署问题
• 可生成辅助脚本，其中 install.sh 是规范的 apply 步骤，另可生成 uninstall.sh、reload.sh、start.sh、stop.sh、restart.sh
• 会识别并交付运行所需的 repo 内配套文件，例如挂载配置、初始化资源和辅助脚本
• 在声称结果可运行前，会检查环境变量完整性，而不是只做 env 摘要
• 鼓励在 planning 阶段显式提出高影响问题，并在 finalize 与 execution 阶段使用 support files 与 env completeness 检查清单
• 当已批准的镜像策略使用 fully qualified registry images 时，可规划 opt-in 的 AutoUpdate=registry
• 说明 rootless / rootful 应用目标路径、部署说明与验证步骤

设计原则

• 优先选择满足需求的最轻运行模式
• 将规划、审阅、生成拆成明确阶段
• 不虚构部署相关取值
• 对有损映射保持显式说明
• 优先输出可维护的结果，而不是机械一比一转换
• 默认先输出到当前目录供审查，再执行安装
• 当 pod 分组已经能清晰表达意图时，优先采用 pod-first 拓扑而不是保留 bridge 网络
• 确保运行所需的 support files 保留在已审阅的当前目录交付集中，并通过绝对主机路径被 Quadlet 引用，而不是由 install.sh 复制进 Quadlet 单元目录

运行模式

• advice：解释映射方式或审查输入，不写最终产物
• design：执行 planning 和交互式 finalize 审阅，但在生成可运行产物前停止
• generate：在 planning、交互式 finalize 审阅和 execution 之后，生成已批准的可运行产物

工作流

完整工作流分为三个明确阶段：Planning、Finalize、Execution。

• advice 通常停留在 Planning，或给出不进入全流程的定向答复
• design 使用 Planning 和 Finalize
• generate 使用全部三个阶段

Planning 必须先向用户确认仍未解决的高影响决策，之后才能继续。 Finalize 会在这些 planning 问题已经讨论过之后，以对话方式进行交互式审阅。 只有在用户审阅并确认 finalize 审阅结果或提出修改后，才能进入 Execution。

文档说明

• SKILL.md：运行模式、工作流和高层规则
• references/compose-mapping.md：Compose 字段映射与拓扑决策
• references/env-strategy.md：env 处理、完整性校验与 typo 检测
• references/github-repo-intake.md：仓库发现与 canonical 输入选择
• references/deployment-notes.md：部署说明
• references/validation.md：验证与排障

限制

本 skill 不保证 Docker Compose 语义与 Podman Quadlet 语义完全等价。

许可证

MIT