mirror of
https://github.com/bestnite/quadlet-migrator-skill.git
synced 2026-04-03 22:53:28 +00:00
Clarify README wording and Quadlet reference rules.
Rewrite the README in plainer language and document podman-systemd.unit.5.md as the gold standard when Quadlet-specific behavior is unclear. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
62
README.md
62
README.md
@@ -2,58 +2,58 @@
|
||||
|
||||
[English](./README.md) | [简体中文](./README.zh-CN.md)
|
||||
|
||||
A skill for migrating `docker run` commands and Docker Compose-style deployments into maintainable Podman Quadlet units.
|
||||
A skill that helps turn `docker run` commands and Docker Compose setups into Podman Quadlet files you can review, adjust, and apply.
|
||||
|
||||
## What it does
|
||||
|
||||
- translates `docker run` and Compose-style inputs into Quadlet-oriented designs
|
||||
- writes generated artifacts to the current directory by default so they can be reviewed before being applied
|
||||
- asks about the output location only when the user requested another location or an existing-file conflict requires a decision
|
||||
- helps decide between `.container`, `.pod`, `.network`, `.volume`, and `.build`, with a pod-first bias for multi-container services
|
||||
- preserves `.env` / `env_file` workflows when appropriate
|
||||
- reduces large env templates into a small set of high-impact deployment questions
|
||||
- can generate helper scripts with `install.sh` as the canonical apply step, plus `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
|
||||
- identifies required repo-local support files such as mounted config, init assets, and helper scripts that must ship with the result
|
||||
- validates env completeness before claiming runnable output
|
||||
- encourages explicit planning questions plus finalize and execution checklists for support files and env completeness
|
||||
- supports opt-in `AutoUpdate=registry` planning when the approved image strategy uses fully qualified registry images
|
||||
- explains rootless vs rootful apply targets, deployment notes, and validation steps
|
||||
- converts `docker run` commands and Docker Compose setups into Podman Quadlet files
|
||||
- writes the generated files to the current directory first so you can review them before installing them
|
||||
- asks about the output location only when you already requested another location or existing files would conflict
|
||||
- helps choose between `.container`, `.pod`, `.network`, `.volume`, and `.build`, usually preferring a pod for related multi-container services
|
||||
- keeps `.env` / `env_file` workflows when they still fit the deployment
|
||||
- turns large env templates into a short list of decisions the user actually needs to make
|
||||
- can generate helper scripts such as `install.sh`, `uninstall.sh`, `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh`
|
||||
- finds files from the current project that the service still needs when it runs, such as mounted config, setup data, and helper scripts
|
||||
- checks that env files are complete before calling the result runnable
|
||||
- asks the user to confirm important deployment choices during planning, then uses clear review and execution checklists
|
||||
- can optionally plan `AutoUpdate=registry` when the chosen image uses a complete image name that includes the registry, such as `docker.io/...` or `ghcr.io/...`
|
||||
- explains rootless vs rootful install paths, deployment notes, and validation steps
|
||||
|
||||
## Design principles
|
||||
|
||||
- prefer the lightest operating mode that matches the request
|
||||
- separate planning, review, and generation into explicit phases
|
||||
- use the simplest mode that fits the request
|
||||
- keep planning, review, and file generation as separate steps
|
||||
- do not invent deployment-specific values
|
||||
- make lossy mappings explicit
|
||||
- prefer maintainable output over mechanical one-to-one translation
|
||||
- default to review-first output in the current directory before installation
|
||||
- prefer pod-first topology over preserving bridge networking when pod grouping expresses the intent cleanly
|
||||
- ensure runtime-required support files remain in the reviewed current-directory deliverable set and are referenced from Quadlet via absolute host paths, rather than being copied by `install.sh` into the Quadlet unit directory
|
||||
- call out behavior changes when a mapping is lossy
|
||||
- prefer output that is easy to understand and maintain
|
||||
- write files to the current directory for review before installation
|
||||
- prefer pod-based grouping when it is the clearest fit for a multi-container service
|
||||
- keep required extra files in the reviewed output and point to them with absolute paths on the host machine instead of copying them into the Quadlet unit directory
|
||||
|
||||
## Operating modes
|
||||
|
||||
- `advice`: explain mappings or review source inputs without writing final artifacts
|
||||
- `design`: perform planning and interactive finalize review, then stop before runnable artifact generation
|
||||
- `generate`: produce approved runnable artifacts after planning, interactive finalize review, and execution
|
||||
- `advice`: explain the mapping, review source inputs, or answer targeted questions without writing final files
|
||||
- `design`: do planning and a final interactive review, then stop before generating runnable files
|
||||
- `generate`: do planning, the final interactive review, and execution, then generate the approved runnable files
|
||||
|
||||
## Workflow
|
||||
|
||||
The full workflow has three explicit phases: `Planning`, `Finalize`, and `Execution`.
|
||||
The workflow has three phases: `Planning`, `Finalize`, and `Execution`.
|
||||
|
||||
- `advice` usually stays in `Planning` or gives a targeted answer without entering all phases
|
||||
- `design` uses `Planning` and `Finalize`
|
||||
- `generate` uses all three phases
|
||||
- `advice` usually stays in `Planning` or answers a focused question directly
|
||||
- `design` includes `Planning` and `Finalize`
|
||||
- `generate` includes all three phases
|
||||
|
||||
Planning must ask the user to confirm unresolved high-impact decisions before moving forward.
|
||||
Finalize happens as an interactive review in conversation after those planning questions have already been discussed.
|
||||
Execution starts only after the user has reviewed and confirmed the finalize review or requested edits.
|
||||
Planning is where unresolved deployment decisions are gathered and confirmed with the user.
|
||||
Finalize is a review step in the conversation after those decisions have been discussed.
|
||||
Execution starts only after the user approves that review.
|
||||
|
||||
## References
|
||||
|
||||
- `SKILL.md` contains the operating modes, workflow, and high-level rules
|
||||
- `references/compose-mapping.md` covers field mapping and topology decisions
|
||||
- `references/env-strategy.md` covers env handling, completeness validation, and typo detection
|
||||
- `references/github-repo-intake.md` covers repository discovery and canonical input selection
|
||||
- `references/github-repo-intake.md` covers how the skill finds the right repository entry point
|
||||
- `references/deployment-notes.md` covers deployment guidance
|
||||
- `references/validation.md` covers validation and troubleshooting
|
||||
|
||||
|
||||
@@ -2,58 +2,58 @@
|
||||
|
||||
[English](./README.md) | [简体中文](./README.zh-CN.md)
|
||||
|
||||
一个 skill，用来将 `docker run` 命令和 Docker Compose 风格部署迁移为可维护的 Podman Quadlet 单元。
|
||||
一个 skill，用来把 `docker run` 命令和 Docker Compose 配置转换成可审阅、可调整、可应用的 Podman Quadlet 文件。
|
||||
|
||||
## 功能概览
|
||||
|
||||
- 将 `docker run` 和 Compose 风格输入转换为面向 Quadlet 的设计
|
||||
- 默认先把生成产物写到当前目录，便于审查后再应用
|
||||
- 只有在用户已要求其他位置，或现有文件冲突需要决策时，才询问输出位置
|
||||
- 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择，并对多容器服务默认偏向 pod-first 拓扑
|
||||
- 将 `docker run` 命令和 Docker Compose 配置转换成 Podman Quadlet 文件
|
||||
- 默认先把生成文件写到当前目录，方便你在安装前先审阅
|
||||
- 只有在你已经指定其他位置，或现有文件会发生冲突时，才询问输出位置
|
||||
- 帮助在 `.container`、`.pod`、`.network`、`.volume`、`.build` 之间做选择；对有关联的多容器服务，通常优先用 pod
|
||||
- 在合适时保留 `.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 应用目标路径、部署说明与验证步骤
|
||||
- 把庞杂的 env 模板收敛成用户真正需要确认的少量问题
|
||||
- 可生成辅助脚本，例如 `install.sh`、`uninstall.sh`、`reload.sh`、`start.sh`、`stop.sh`、`restart.sh`
|
||||
- 识别服务运行时仍需要的项目内文件，例如挂载配置、初始化数据和辅助脚本
|
||||
- 在声称结果可运行前，检查 env 文件是否完整
|
||||
- 在 planning 阶段先确认关键部署决策，并在审阅和执行阶段使用清晰的检查清单
|
||||
- 当所选镜像使用包含仓库地址的完整镜像名时，例如 `docker.io/...` 或 `ghcr.io/...`，可选规划 `AutoUpdate=registry`
|
||||
- 说明 rootless / rootful 安装路径、部署说明和验证步骤
|
||||
|
||||
## 设计原则
|
||||
|
||||
- 优先选择满足需求的最轻运行模式
|
||||
- 将规划、审阅、生成拆成明确阶段
|
||||
- 用能满足需求的最简单模式
|
||||
- 将 planning、审阅、生成文件分成独立步骤
|
||||
- 不虚构部署相关取值
|
||||
- 对有损映射保持显式说明
|
||||
- 优先输出可维护的结果，而不是机械一比一转换
|
||||
- 默认先输出到当前目录供审查，再执行安装
|
||||
- 当 pod 分组已经能清晰表达意图时，优先采用 pod-first 拓扑而不是保留 bridge 网络
|
||||
- 确保运行所需的 support files 保留在已审阅的当前目录交付集中，并通过绝对主机路径被 Quadlet 引用，而不是由 `install.sh` 复制进 Quadlet 单元目录
|
||||
- 如果映射会带来行为变化，要明确说出来
|
||||
- 优先产出容易理解、容易维护的结果
|
||||
- 先把文件写到当前目录审阅，再决定是否安装
|
||||
- 对多容器服务，如果用 pod 更清晰，就优先用 pod
|
||||
- 运行仍需要的额外文件保留在已审阅的输出中，并通过主机上的绝对路径引用，而不是复制进 Quadlet 单元目录
|
||||
|
||||
## 运行模式
|
||||
|
||||
- `advice`：解释映射方式或审查输入，不写最终产物
|
||||
- `design`：执行 planning 和交互式 finalize 审阅，但在生成可运行产物前停止
|
||||
- `generate`：在 planning、交互式 finalize 审阅和 execution 之后，生成已批准的可运行产物
|
||||
- `advice`：解释映射方式、审查输入，或回答定向问题，不写最终文件
|
||||
- `design`：执行 planning 和最后一轮交互式审阅，但在生成可运行文件前停止
|
||||
- `generate`：执行 planning、最后一轮交互式审阅和 execution，然后生成已批准的可运行文件
|
||||
|
||||
## 工作流
|
||||
|
||||
完整工作流分为三个明确阶段：`Planning`、`Finalize`、`Execution`。
|
||||
工作流分为三个阶段：`Planning`、`Finalize`、`Execution`。
|
||||
|
||||
- `advice` 通常停留在 `Planning`，或给出不进入全流程的定向答复
|
||||
- `design` 使用 `Planning` 和 `Finalize`
|
||||
- `generate` 使用全部三个阶段
|
||||
- `advice` 通常停留在 `Planning`，或直接回答一个聚焦的问题
|
||||
- `design` 包含 `Planning` 和 `Finalize`
|
||||
- `generate` 包含全部三个阶段
|
||||
|
||||
Planning 必须先向用户确认仍未解决的高影响决策，之后才能继续。
|
||||
Finalize 会在这些 planning 问题已经讨论过之后，以对话方式进行交互式审阅。
|
||||
只有在用户审阅并确认 finalize 审阅结果或提出修改后，才能进入 Execution。
|
||||
Planning 用来收集并确认仍未决定的部署问题。
|
||||
Finalize 是在这些问题讨论清楚之后进行的对话式审阅。
|
||||
只有在用户批准这次审阅后，才进入 Execution。
|
||||
|
||||
## 文档说明
|
||||
|
||||
- `SKILL.md`：运行模式、工作流和高层规则
|
||||
- `references/compose-mapping.md`：Compose 字段映射与拓扑决策
|
||||
- `references/env-strategy.md`：env 处理、完整性校验与 typo 检测
|
||||
- `references/github-repo-intake.md`：仓库发现与 canonical 输入选择
|
||||
- `references/github-repo-intake.md`：说明 skill 如何找到正确的仓库入口
|
||||
- `references/deployment-notes.md`：部署说明
|
||||
- `references/validation.md`：验证与排障
|
||||
|
||||
|
||||
3
SKILL.md
3
SKILL.md
@@ -278,7 +278,8 @@ Decide early whether the deployment is rootless or rootful, because this changes
|
||||
- For rootful deployments, the default apply target directory is `/etc/containers/systemd/` unless the user asks for a different placement.
|
||||
- For rootless long-running services, remind the user about lingering if relevant. See `references/deployment-notes.md`.
|
||||
|
||||
When you need authoritative details about supported search paths, unit semantics, option names, or debugging, read `references/podman-systemd.unit.5.md`.
|
||||
When you need authoritative details about supported search paths, unit semantics, option names, generated-service behavior, or debugging, read `references/podman-systemd.unit.5.md`.
|
||||
If a Quadlet mapping, option meaning, or supported behavior is unclear or seems to conflict with higher-level guidance, treat `references/podman-systemd.unit.5.md` as the gold standard for Quadlet-specific behavior and align the result to it.
|
||||
|
||||
## Reference routing
|
||||
|
||||
|
||||
Reference in New Issue
Block a user