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/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: {}
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