xinetzone/SpecWeave / .agents/skills/client-overlay-scaffold
client-overlay-scaffold
Verified在 apps/containers/client/overlays/ 新建 podman-compose 工作负载叠加层(onnx-quantized/native-dev/agent-monetize-dev 的下一个栈)的脚手架。当用户要求新增/创建 client 叠加层、新工作负载栈、新 invoke xxx.* compose 命名空间、照三栈再做一个栈、给 rootless 基底加声明式服务栈时,必须使用此技能。v1.1 起骨架改为「声明式 StackSpec + extends rootless-base 基段」:栈模块只写 <NAME>_SPEC(jpman_client/tasks/overlay_core.py 的 StackSpec)+ TASKS=make_stack_tasks(spec) + 六别名,compose.yaml 以 extends 继承 overlays/_shared/base-rootless.yaml(rootless 三必需/凭证四变量/network_mode bridge 单一事实源),不再复制任何生命周期代码。封装:栈形态决策树、标准 12 件套文件清单、compose/invoke/.env 三套骨架模板(templates/)、rootless 三必需与 Windows 桥接不可变纪律、7 个必改接线登记点(含 tests/test_tasks_surface.py 黄金清单与 tests/test_compose_merge.py GOLDEN 表)、静态门禁→真实构建→E2E→独立 Review 验证链,以及 podman-compose 1.6 extends rec_merge/OCI/双 ABI/SONAME/.dockerignore 等全部实测踩坑。不要凭记忆手写 compose 与任务模块——本技能的骨架与 Gotchas 来自三个已交付栈(quant/native/monetize)的真实 E2E 与两轮独立审查。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 27.6 KB |
| references/delivery-checklist.md | markdown | 4.7 KB |
| templates/compose.yaml.skeleton | other | 3.8 KB |
| templates/env.example.skeleton | other | 2.7 KB |
| templates/namespace.py.skeleton | other | 5.7 KB |
templates/compose.yaml.skeleton
View on GitHub---
# __STACK__ 叠加栈 - Compose Specification(podman-compose / rootless)
#
# 本文件由 client-overlay-scaffold v1.1 骨架生成。替换全部 __X__ 占位符:
# __STACK__ 栈目录名/name / __NS__ 命名空间 / __SVC__ 服务名 /
# __IMAGE__ 镜像标签 / __SSH_PORT__ __JUPYTER_PORT__ 端口 /
# __CONTAINERFILE__ Containerfile 文件名 / __NSU__ env 前缀
#
# 设计依据(不可变,详见技能 SKILL.md §7):
# 顶部 extends ../_shared/base-rootless.yaml(rootless-base 服务)。
# rootless 三必需(devices /dev/fuse + security_opt label=disable
# + cgroupns host)、凭证四变量(USER_PASSWORD/JUPYTER_TOKEN/
# SSH_PUBLIC_KEY/GRANT_SUDO)、network_mode bridge、
# org.specweave.managed-by label、restart 均在基段单一事实源,
# 本文件【严禁重复声明】;严禁 privileged。
# bind 一律长语法 + create_host_path(G1)。
#
# extends 合并语义(podman-compose 1.6.0 vendor 源码实证):
# rec_merge({}, base, current)——dict 深合并(environment/labels 取键并集)
# /普通 list 追加/command、entrypoint 无条件替换;volumes 特例:仅短语法
# 字符串按 target 去重且覆盖方获胜,【长语法 dict bind 不去重】——本栈
# bind 全用长语法,override 中切勿重声明同一 target(会重复挂载);
# extends.file 在解析阶段(_parse_compose_file L2844-L2849)按引用文件
# 目录重写,invoke 绝对 --file + 任意 cwd、裸 podman-compose 在栈目录
# 执行均可解析。
#
# 两种驱动:① invoke __NS__.*(apps/containers/client 下);
# ② 裸 podman-compose(本目录 cp .env.example .env)。
name: __STACK__
services:
__SVC__:
extends:
file: ../_shared/base-rootless.yaml
service: rootless-base
container_name: ${__NSU___CONTAINER_NAME:-__STACK__}
image: ${__NSU___IMAGE_TAG:-__IMAGE__}
build:
context: .
dockerfile: __CONTAINERFILE__
args:
BASE_IMAGE: ${BASE_IMAGE:-localhost/jupyter-podman-rootless:latest}
PIP_MIRROR: ${PIP_MIRROR:-official}
# 不需要 conda 镜像源的栈删除本行(同时删 .env 键与 StackSpec
# conda_mirror 保持 False;需要时 StackSpec conda_mirror=True)
CONDA_MIRROR: ${CONDA_MIRROR:-official}
ports:
- "${__NSU___SSH_PORT:-__SSH_PORT__}:22"
- "${__NSU___JUPYTER_PORT:-__JUPYTER_PORT__}:8888"
volumes:
# 通用工作区(invoke 路径解析为绝对 POSIX 并自动 mkdir;
# 裸 compose 的相对路径相对本文件,../../workspace = client/workspace)
- type: bind
source: ${__NSU___WORKSPACE:-../../workspace}
target: /workspace
bind:
create_host_path: true
# 【形态 B 按需复制:源码/数据 bind,每个都用长语法;裸 compose 的
# 相对路径按本文件所在 overlays/<stack>/ 的层级数算(apps/ 下资源
# 通常 ../../../../<dir>,external/ 下 ../../../../../<dir>);
# 同时在 StackSpec.source_mounts 与两处 .env.example 登记同名键】
# - type: bind
# source: ${__NSU___SRC_PATH:-../../../../apps/<dir>}
# target: /workspace/<name>
# bind:
# create_host_path: true
# 【命名卷示例:构建缓存等(短语法对 named volume 安全)】
# - __STACK__-cache:/root/.cache/<tool>
environment:
# 凭证四变量与 rootless 三必需由 rootless-base 继承,勿在此重复声明。
# 【仅放栈业务环境变量;四凭证全局共用,不要改名】
# PYTHONPATH: /workspace/<name>/src
labels:
# managed-by 由基段继承(labels 深合并取并集),这里只写组件标签
org.specweave.component: "__SVC__"
# 【使用命名卷时在此声明】
# volumes:
# __STACK__-cache: {}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |