Skip to content

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 与两轮独立审查。

templates/namespace.py.skeleton

View on GitHub
"""__STACK__ 工作负载叠加栈的 podman-compose 编排任务(opt-in 命名空间)。

由 client-overlay-scaffold v1.1 骨架生成。**声明式栈,禁止复制生命周期
代码**:替换全部 __X__ 占位符后本文件即完整模块——
  __STACK__ 栈目录/project name / __NS__ 命名空间(Collection 名,小写短名)/
  __NSU__ 命名空间大写形(<NAME>_SPEC 变量名与 env 前缀值,如 MONETIZE)/
  __SVC__ compose 服务名 / __IMAGE__ 默认镜像标签 /
  __SSH_PORT__ __JUPYTER_PORT__ 默认端口 / __CONTAINERFILE__ Containerfile 文件名。

唯一事实源是下方的 __NSU___SPEC(StackSpec);六个任务
(build/up/down/ps/logs/smoke)全部由 overlay_core.make_stack_tasks
工厂生成,门控/argv/环境解析/残留自愈/冒烟双路径不在本模块重复。

定位(红线):
  - 本模块**禁止 import podman**,只通过内核子进程驱动 podman-compose;
  - 与根 SDK→CLI 两层平行,禁止回流 invoke run;
  - 内核 overlay_core 与 jpman_common 零栈知识,栈差异只能经 SPEC 字段注入。

形态 B 的 exec 长任务(编译/打包)见文件尾部模板,参照 native.py
(build-tvm/wheel)与 monetize.py(build-native/wheel)的真实写法。
"""
from __future__ import annotations

# 形态 A(无长任务)只需下列导入(与 quant.py 一致);
# 形态 B(source_mounts / exec 长任务)解开第二段导入并在尾部追任务。
from .overlay_core import SmokeSpec, StackSpec, TaskDocs, make_stack_tasks

# from invoke import Context, task
# from .overlay_core import (
#     SourceMount,
#     ensure_runtime_ready,
#     gates,
#     require_running,
#     run_compose,
# )

__NSU___SPEC = StackSpec(
    namespace="__NS__",
    project="__STACK__",
    service="__SVC__",
    overlay_subdir="__STACK__",
    containerfile="__CONTAINERFILE__",
    default_image_tag="__IMAGE__",
    default_base_image="localhost/jupyter-podman-rootless:latest",
    env_prefix="__NSU__",
    docs=TaskDocs(
        build="构建 __STACK__ 叠加镜像(构建期守卫失败即失败)。",
        up="渲染并启动 __STACK__ 栈(podman-compose up -d,默认随带构建)。",
        down="停止并删除 __STACK__ 栈容器与网络(bind 数据不受影响)。",
        ps="查看 __STACK__ 栈服务状态。",
        logs="跟踪 __STACK__ 栈服务日志(Ctrl+C 退出,不影响容器运行)。",
        smoke="运行 __STACK__ 冒烟:工具链守卫(始终)+ 栈运行时冒烟。",
    ),
    down_volumes_help="同时删除栈命名卷(默认保留以加速重复运行)",
    ssh_default="__SSH_PORT__",
    jupyter_default="__JUPYTER_PORT__",
    # jupyter_banner_note="(内核:Python 3.14 (__NS__ dev))",  # 按需
    # build_done_label="叠加镜像",      # quant 历史用「量化叠加镜像」
    # build_next_hint="",               # 构建完成行尾补充
    # up_footer=(),                     # 空=自动单行;native 用三行提示长任务
    gpu_override=False,               # 有 compose.gpu.yaml 且 up/smoke 要 --gpu 才 True(quant)
    conda_mirror=False,               # build 要 --conda-mirror 才 True(native)
    auto_shortflags=False,            # quant 历史为 True,新栈保持 False
    # 【形态 B:宿主源码/数据 bind;先解开上方 SourceMount 导入。
    # anchor="repo" 锚仓库根(default_rel 写 "apps/<dir>" / "external/<dir>"),
    # anchor="client" 锚 client 根】
    source_mounts=(
        # SourceMount("__NSU___SRC_PATH", "apps/<app-dir>", "<说明>"),
    ),
    smoke=SmokeSpec(
        # 形态 A 通常 /opt/conda/envs/main/bin/python(cp314t);
        # 形态 B 编译/打包栈常为 /opt/conda/bin/python(cp314 GIL)——按栈改
        python="/opt/conda/envs/main/bin/python",
        smoke_dir="/opt/__STACK__-smoke",
        exec_scripts=("_guards.py",),
        standalone_scripts=("_guards.py",),
        running_note="检测到运行中的栈,经 compose exec 执行守卫与冒烟:",
        standalone_note="栈未运行,使用一次性容器仅执行工具链守卫(运行时冒烟需先 up):",
        done_message="冒烟通过",
    ),
    # WSL 透明桥接透传的栈专属键(与 compose 插值键、两处 .env.example 对齐;
    # 通用凭证/镜像源键由 utils._BRIDGE_COMMON_ENV_KEYS 内置,勿在此重复)
    bridge_env_keys=(
        "__NSU___IMAGE_TAG", "__NSU___CONTAINER_NAME", "__NSU___WORKSPACE",
        "__NSU___SSH_PORT", "__NSU___JUPYTER_PORT",
        # "__NSU___SRC_PATH",
    ),
    # not_running_hint="__NS__ 栈未运行,请先:invoke __NS__.up --skip-build",
)

TASKS = make_stack_tasks(__NSU___SPEC)
build = TASKS["build"]
up = TASKS["up"]
down = TASKS["down"]
ps = TASKS["ps"]
logs = TASKS["logs"]
smoke = TASKS["smoke"]


# ---------------------------------------------------------------------------
# 【形态 B:栈内 exec 长任务在此追加(真实写法参照 monetize.py / native.py)】
#
# 固定四步前置:gates → ensure_runtime_ready → require_running → run_compose;
# 环境变量透传把 ["-e", f"KEY={v}"] 插在 "exec" 与服务名之间。
#
# _JOB_SCRIPT = "/opt/__STACK__-builder/scripts/<job>.sh"
#
# @task(auto_shortflags=False)
# def <job>(c: Context) -> None:
#     """栈内执行 <job>(长任务)。"""
#     gates(__NSU___SPEC)
#     ensure_runtime_ready(__NSU___SPEC)
#     require_running(c, __NSU___SPEC)
#     run_compose(
#         c, __NSU___SPEC, "exec", "-T", __NSU___SPEC.service,
#         "bash", _JOB_SCRIPT, pty=True,
#     )
#
# 注册:tasks/__init__.py 循环 add_task(TASKS) 后单独
#       <ns>_ns.add_task(<ns>.<job>, "<job>")
# ---------------------------------------------------------------------------
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall