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/env.example.skeleton

View on GitHub
# __STACK__ 叠加栈 - compose 插值变量模板
#
# 由 client-overlay-scaffold v1.1 骨架生成。替换 __X__ 占位符后使用。
#
# 三处事实源(键集合必须逐一对应,新增/删除键三处同改):
#   ① compose.yaml 的 ${...} 插值键(本文件);
#   ② StackSpec.bridge_env_keys:下列「桥接键」区块的键必须与其逐一相同
#      (Windows 透明桥接 WSL 时按此清单透传;通用凭证/镜像源键由
#      utils._BRIDGE_COMMON_ENV_KEYS 内置,不进 bridge_env_keys);
#   ③ 根 client .env.example 的注释态 <NSU> 段(与本文件同键)。
#
# 两种驱动:
#   ① invoke __NS__.*(推荐):在 apps/containers/client/.env 写同名键,
#      任务以 load_dotenv(override=False) 注入——shell export > root .env
#      > compose 默认;invoke 会把宿主路径解析为绝对 POSIX 并做存在性校验。
#   ② 裸 podman-compose:在本目录复制为 .env(自动读取)。
#
# Windows 原生 CPython:invoke 自动透明桥接 WSL 发行版(COMPOSE_WSL_DISTRO
#   指定/=none 关闭);或 invoke env.run-cmd --cmd 'inv __NS__.up'。

# ── 桥接键(StackSpec.bridge_env_keys 与此块逐一对应,勿含凭证/镜像源)──
# 镜像标签 / 容器名(compose project name 固定为 __STACK__)
__NSU___IMAGE_TAG=__IMAGE__
__NSU___CONTAINER_NAME=__STACK__

# 端口映射(与已运行栈错开;client 现有:quant 2222/8888、native 2223/8890、monetize 2224/8892)
__NSU___SSH_PORT=__SSH_PORT__
__NSU___JUPYTER_PORT=__JUPYTER_PORT__

# 通用工作区(绑定容器 /workspace)
__NSU___WORKSPACE=../../workspace

# 【形态 B:源码/数据路径。每个键同时登记三处:① 本文件与根 .env.example;
# ② compose.yaml 长语法 bind 的 ${...};③ StackSpec.source_mounts 的 env
# 与 bridge_env_keys。invoke 做存在性硬校验;裸 compose 相对路径相对本文件
# 所在 overlays/<stack>/ 目录(apps/ 下通常 ../../../../<dir>)】
# __NSU___SRC_PATH=../../../../apps/<dir>

# ── 非桥接键(基段 rootless-base 与 build args 插值;通用键不进 bridge_env_keys)──
# 凭证(留空 = 基底 entrypoint 自动生成并打印)
USER_PASSWORD=
JUPYTER_TOKEN=
SSH_PUBLIC_KEY=
GRANT_SUDO=yes

# 构建期镜像源(official|aliyun|tuna)。独立 inv __NS__.build 只认命令行
# 参数;此处的值在 inv __NS__.up 的 compose 内联 build 与裸 compose build 生效
PIP_MIRROR=official
# 不需要 conda 源的栈删除下一行(同时删 compose.yaml 对应 build arg,
# StackSpec.conda_mirror 保持 False)
CONDA_MIRROR=official
# 基底镜像(compose build args,通常无需改)
# BASE_IMAGE=localhost/jupyter-podman-rootless:latest
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: 197kUpdated Claude CodeCodexVerifiedInstall