feat: add skill init/check and isolate builder makefile

Give ack, builder, and deployer an explicit init/check mode that reports
missing project config instead of failing mid-work. Point builder at
makefile.builder so its contract targets do not collide with an existing
Makefile.

skills/deployer/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: deployer
 description: >-
-  管理两类部署：多机 Docker Compose（仓库存 compose.yaml 与静态配置，本 skill 脚本
-  同步到 SSH 节点后 docker compose 应用），以及 Argo CD GitOps（改 GitOps 仓库清单、
-  开 PR/MR，用户合并后由 Argo CD 同步）。当用户要求部署、同步、升级、重启远程
-  Compose 服务，向节点装 deb，新增/迁移/下线服务，梳理节点清单，make deploy TGT、
-  _config.yaml、rsync、tar over SSH、NAS 部署失败；或要求 ArgoCD / GitOps / K8s
-  部署、更新 Application、升镜像 tag、开 MR 让用户合并部署；或 ACK 要求拉起/
-  重布项目测试环境时使用。
+  初始化或检查项目部署配置，并管理两类部署：多机 Docker Compose（仓库存
+  compose.yaml 与静态配置，本 skill 脚本同步到 SSH 节点后 docker compose 应用），
+  以及 Argo CD GitOps（改 GitOps 仓库清单、开 PR/MR，用户合并后由 Argo CD 同步）。
+  当用户要求初始化 deployer、接入测试/生产环境、检查 .pouch/deployer 是否齐全；
+  或部署、同步、升级、重启远程 Compose 服务，向节点装 deb，新增/迁移/下线服务，
+  梳理节点清单，make deploy TGT、_config.yaml、rsync、tar over SSH、NAS 部署失败；
+  或要求 ArgoCD / GitOps / K8s 部署、更新 Application、升镜像 tag、开 MR 让用户
+  合并部署；或 ACK 要求拉起/重布项目测试环境时使用。
 ---
 
 # deployer：Compose 节点与 Argo CD GitOps
@@ -18,7 +19,16 @@ description: >-
 - **Argo CD**：改 GitOps 仓库清单 → 开 PR/MR → 用户合并 → Argo CD 同步。不要用
   Compose 的 `sync.py`/`remote.py` 去推集群。
 
----
+开始时解析当前 `SKILL.md` 所在目录，记为 `<skill-dir>`。优先
+`git rev-parse --show-toplevel` 解析项目根。不要创建 `.pouch/deployer/` 之外的
+假配置中心，也不要用 `pouch init deployer`。
+
+## 选择模式
+
+- 用户要求初始化、接入 deployer，或给新项目建测试/生产环境：执行“初始化”。
+- 用户要求检查 `.pouch/deployer`、node、compose 是否齐全：执行“检查”。
+- 用户要求部署、同步、升级、重启、装 deb、开 GitOps MR：执行下面对应轨道步骤。
+  发现不了服务或解析不出 node 时停止，转入“初始化”。不要静默初始化。
 
 ## 何时使用
 
@@ -29,6 +39,7 @@ description: >-
 - 提到 `make deploy TGT=...`、`TGT=`、`_config.yaml`、rsync/tar 同步
 - Argo CD / GitOps / 集群部署：新增 Application、改清单、升镜像 tag、开 MR 等用户合并
 - ACK Coordinator 拉起或重布项目测试环境（`.pouch/deployer/<env>`）
+- 初始化 deployer、给项目接上 test/prod、检查部署配置缺什么
 
 ## 不适用
 
@@ -98,6 +109,54 @@ my-project/
 （如 `my-project-prod`），防止同主机多项目的同名环境互相覆盖；
 `_config.yaml` 写 `name:` 可显式指定。
 
+## 初始化
+
+独立配置中心仓库（已设 `DEPLOYER_ROOT`）只做检查，不要改成项目内布局。
+
+1. 探测：`.pouch/deployer/`、根目录 `compose.yaml`/`docker-compose.yml`、
+   `Dockerfile`、ACK `intents.testEnvironment`、`.pouch/deployer/argocd.yaml`。
+2. Compose 与 Argo 都有且意图不清：先问。两边都要也可以，必须分开确认。
+3. **Compose / 新项目**（ACK 默认需要 `test`）：
+   - 问环境：默认只建 `test`。`prod`/`dev` 用户点名再加。不默默建空的 prod。
+   - 问 SSH Host 别名（必须在 `~/.ssh/config`）。没给就**不要写假 node**；
+     目录可以建，`_config.yaml` 列为待配置。
+   - 有根目录 compose：提议迁到 `.pouch/deployer/<env>/`，确认后才动。
+   - 只有 Dockerfile：可给**单服务** compose 草稿（镜像名来自仓库名），用户确认
+     后写入。不发明多服务网格。
+4. **Argo**：只问 GitOps `repo`（或 `repo_dir`），写 `.pouch/deployer/argocd.yaml`。
+   不 clone、不开 MR、不 `kubectl apply`。
+5. 运行（不 SSH、不 up）：
+
+   ```bash
+   python3 -I -S <skill-dir>/scripts/deploy/check.py --project <project-root>
+   ```
+
+6. 按下面格式报告。缺 `node` / compose / ssh 别名 = 部分完成或阻塞。
+   不覆盖已有 compose/`_config.yaml`。除非用户明确要求，不部署、不提交。
+
+```text
+## deployer 初始化：完成 | 部分完成 | 阻塞
+
+已具备: …
+待配置: 路径 + 字段 + 可粘贴示例 + 缺了会挡住哪步
+工具链: ssh / rsync（缺则怎么装，不擅自安装）
+下一步: 一句话
+```
+
+`_config.yaml` 示例（`node` 必须是用户给出的 SSH Host 别名）：
+
+```yaml
+# .pouch/deployer/_config.yaml
+node: my-vps
+base_path: /opt/app
+```
+
+## 检查
+
+只读。运行 `scripts/deploy/check.py --project <project-root>`，用同一报告格式，
+标题改为 `## deployer 检查：…`。不写文件、不 SSH 连接。用户明确要求修复后再转入
+初始化。
+
 ## 被 ACK 调用
 
 ACK 的「运行测试环境」和回归前布环境会加载本 skill，对项目
@@ -267,6 +326,7 @@ python3 <skill-dir>/scripts/deploy/deb.py <target> apt https://example.com/foo_1
 | `scripts/deploy/remote.py` | SSH 远程 docker compose：up/recreate/restart/upgrade/ps/logs |
 | `scripts/deploy/deb.py` | deb 包分发安装：push(scp+apt)/scp/dpkg/apt(URL) |
 | `scripts/deploy/list.py` | 扫描全部可部署服务 |
+| `scripts/deploy/check.py` | 只读就绪检查：布局、compose、node、ssh config、工具链 |
 
 ## references/