Lixueduan | 李学端修改

1
2

Volcano = 自定义调度器 + 队列管理 + 作业管理
Kueue = 队列管理 + 配额管理（调度交给 kube-scheduler）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

┌─────────────────────────────────────────────────────┐
│ Cohort │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ClusterQueue A │ │ ClusterQueue B │ │
│ │ (nominal: 5GPU) │ │ (nominal: 5GPU) │ │
│ │ borrowLimit: 5 │ │ borrowLimit: 5 │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ ResourceFlavor: A100 / T4 / CPU │
└─────────────────────────────────────────────────────┘
 │ │
 LocalQueue A LocalQueue B ← Namespaced
 (team-a) (team-b)
 │ │
 Workload 1 Workload 2 ← 用户的 Job

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

用户提交 Job (带 kueue.x-k8s.io/queue-name 标签)
 ↓
Kueue 自动创建 Workload 对象
 ↓
Workload 进入 LocalQueue → 找到对应的 ClusterQueue
 ↓
检查 ClusterQueue 是否有足够配额？（允许从 Cohort 借调）
 ├── 没有 → 询问 Cluster Autoscaler 能否扩容？ → 等待扩容
 ↓ (有配额 或 扩容完成)
检查 ClusterQueue 是否配置了 AdmissionCheck？
 ├── 有 → 等待所有 Check 通过 → 最终准入
 └── 没有 → 直接最终准入
 ↓
Kueue 注入 nodeAffinity/tolerations (锁定算力)
 ↓
Job Controller 创建 Pod
 ↓
Kube Scheduler 分配 Pod 到具体节点
 ↓
节点资源不足？ → 触发 Cluster Autoscaler 真正扩容节点 (Provision)

1

kubectl apply --server-side -f https://github.com/kubernetes-sigs/kueue/releases/download/v0.18.1/manifests.yaml

1
2
3
4
5

helm install kueue oci://registry.k8s.io/kueue/charts/kueue \
 --version=0.18.1 \
 --namespace kueue-system \
 --create-namespace \
 --wait --timeout 300s

1

helm uninstall kueue --namespace kueue-system

1

kubectl -n kueue-system get po

1
2

NAME READY STATUS RESTARTS AGE
kueue-controller-manager-665fc6d58-whxcz 1/1 Running 0 60m

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

apiVersion: kueue.x-k8s.io/v1beta2
kind: ResourceFlavor
metadata:
 name: "default-flavor"
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: ClusterQueue
metadata:
 name: "cluster-queue"
spec:
 namespaceSelector: {} # 允许所有命名空间
 resourceGroups:
 - coveredResources: ["cpu", "memory"]
 flavors:
 - name: "default-flavor"
 resources:
 - name: "cpu"
 nominalQuota: 9
 - name: "memory"
 nominalQuota: 9Gi
---
apiVersion: kueue.x-k8s.io/v1beta2
kind: LocalQueue
metadata:
 namespace: "default"
 name: "user-queue"
spec:
 clusterQueue: "cluster-queue"

1

kubectl apply -f queue.yaml

1
2
3
4
5

# ClusterQueue 是否激活
kubectl get clusterqueue cluster-queue -o wide

# LocalQueue 是否就绪
kubectl get localqueue user-queue -n default

1
2
3
4
5
6
7

root@lixd-dev-4:~# kubectl get clusterqueue cluster-queue -o wide
NAME COHORT STRATEGY PENDING WORKLOADS ADMITTED WORKLOADS
cluster-queue BestEffortFIFO 0 0

root@lixd-dev-4:~# kubectl get localqueue user-queue -n default
NAME CLUSTERQUEUE PENDING WORKLOADS ADMITTED WORKLOADS
user-queue cluster-queue 0 0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

apiVersion: batch/v1
kind: Job
metadata:
 name: sample-job
 namespace: default
 labels:
 kueue.x-k8s.io/queue-name: user-queue  # 接入 Kueue 的关键
spec:
 parallelism: 3
 completions: 3
 template:
 spec:
 containers:
 - name: dummy-job
 image: registry.k8s.io/e2e-test-images/agnhost:2.53
 command: ["/bin/sh"]
 args: ["-c", "sleep 30"]
 resources:
 requests:
 cpu: "1"
 memory: "200Mi"
 restartPolicy: Never

1

kubectl apply -f job.yaml

1
2
3
4
5

# 查看 Kueue 自动创建的 Workload
kubectl get workloads -n default

# 查看 Pod
kubectl get pods -n default

1
2
3
4
5
6
7
8
9

root@lixd-dev-4:~# kubectl get workloads -n default
NAME QUEUE RESERVED IN ADMITTED FINISHED AGE
job-sample-job-555d8 user-queue cluster-queue True 9s

root@lixd-dev-4:~# kubectl get pods -n default
NAME READY STATUS RESTARTS AGE
sample-job-j6xdp 1/1 Running 0 14s
sample-job-k4mtm 1/1 Running 0 14s
sample-job-nvjkz 1/1 Running 0 14s

1
2

# 等待任务完成
kubectl get jobs -n default -w

1
2
3

root@lixd-dev-4:~# kubectl get jobs -n default -w
NAME STATUS COMPLETIONS DURATION AGE
sample-job Complete 3/3 34s 44s

1

kubectl get workloads -n default

1
2
3

root@lixd-dev-4:~# kubectl get workloads -n default
NAME QUEUE RESERVED IN ADMITTED FINISHED AGE
job-sample-job-555d8 user-queue cluster-queue True True 49s

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

kind: Pod
spec:
 containers:
 - …
 volumeMounts:
 - name: my-volume
 mountPath: /path/to/directory
 volumes:
 - name: my-volume
 image:
 reference: my-image:tag

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 只挂载镜像中的 models/Qwen2-0.5B 子目录到 /models/qwen2
containers:
 - name: app
 image: busybox:1.36
 volumeMounts:
 - name: model-volume
 mountPath: /models/qwen2
 subPath: Qwen2-0.5B  # 挂载镜像中的这个子路径
 readOnly: true
volumes:
 - name: model-volume
 image:
 reference: registry.example.com/models/all-models:v1
 pullPolicy: IfNotPresent
# 如果 subPath 指定的路径在镜像中不存在，容器创建会报错

1
2
3
4
5
6

mkdir -p models/Qwen2-0.5B models/Llama2-7B
echo "qwen2 model weights" > models/Qwen2-0.5B/model.bin
echo "qwen2 config" > models/Qwen2-0.5B/config.json
echo "llama2 model weights" > models/Llama2-7B/model.bin
echo "llama2 config" > models/Llama2-7B/config.json
echo "app config v1" > app.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

image-builder/
├── Dockerfile
├── app.conf
└── models/
 ├── Qwen2-0.5B/
 │ ├── config.json
 │ └── model.bin
 └── Llama2-7B/
 ├── config.json
 └── model.bin

1
2
3

FROM scratch
COPY ./models /models
COPY ./app.conf /app.conf

1
2

docker build -t registry.example.com/demo/image-volume:v1 .
docker push registry.example.com/demo/image-volume:v1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

apiVersion: v1
kind: Pod
metadata:
 name: image-volume-demo
spec:
 containers:
 - name: app
 image: busybox:1.36
 command: ["sleep", "3600"]
 volumeMounts:
 - name: model-volume
 mountPath: /models
 readOnly: true
 volumes:
 - name: model-volume
 image:
 reference: registry.example.com/demo/image-volume:v1
 pullPolicy: IfNotPresent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

$ kubectl apply -f pod.yaml
pod/image-volume-demo created

$ kubectl get pod image-volume-demo
NAME READY STATUS RESTARTS AGE
image-volume-demo 1/1 Running 0 30s

$ kubectl exec image-volume-demo -- ls -la /models/
total 16
drwxr-xr-x 1 root root 4096 Jun 16 13:03 .
drwxr-xr-x 1 root root 4096 Jun 16 13:03 ..
-rw-r--r-- 1 root root 14 Jun 16 13:03 app.conf
drwxr-xr-x 2 root root 4096 Jun 16 13:03 Qwen2-0.5B
drwxr-xr-x 2 root root 4096 Jun 16 13:03 Llama2-7B

$ kubectl exec image-volume-demo -- cat /models/app.conf
app config v1

$ kubectl exec image-volume-demo -- cat /models/Qwen2-0.5B/config.json
qwen2 config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: v1
kind: Pod
metadata:
 name: image-volume-subpath
spec:
 containers:
 - name: app
 image: busybox:1.36
 command: ["sleep", "3600"]
 volumeMounts:
 - name: model-volume
 mountPath: /models/qwen2
 subPath: Qwen2-0.5B
 readOnly: true
 volumes:
 - name: model-volume
 image:
 reference: registry.example.com/demo/image-volume:v1
 pullPolicy: IfNotPresent

1
2
3
4
5
6
7
8
9

$ kubectl exec image-volume-subpath -- ls -la /models/qwen2/
total 12
drwxr-xr-x 2 root root 4096 Jun 16 13:03 .
drwxr-xr-x 3 root root 4096 Jun 16 13:03 ..
-rw-r--r-- 1 root root 14 Jun 16 13:03 config.json
-rw-r--r-- 1 root root 22 Jun 16 13:03 model.bin

$ kubectl exec image-volume-subpath -- cat /models/qwen2/config.json
qwen2 config

1
2

$ kubectl get pod image-volume-subpath-err -o jsonpath='{.status.containerStatuses[0].state.waiting.message}'
failed to mount image volume: ImageVolumeMountFailed: failed to ensure image subpath "not-exist-dir" in "...": openat not-exist-dir: no such file or directory

1
2

$ kubectl exec image-volume-demo -- sh -c 'echo test > /models/test.txt'
sh: can't create /models/test.txt: Read-only file system

1
2
3

helm repo add kedacore https://kedacore.github.io/charts
helm repo update
helm install keda kedacore/keda --namespace keda --create-namespace

1

kubectl get pods -n keda

1
2

git clone https://github.com/lixueduan/keda-ai-queue-demo.git
cd keda-ai-queue-demo

1

kubectl apply -k deploy/

1

kubectl get pods -n keda-ai-demo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
 name: worker-scaler
 namespace: keda-ai-demo
spec:
 scaleTargetRef:
 name: worker
 pollingInterval: 5
 cooldownPeriod: 60
 minReplicaCount: 0
 maxReplicaCount: 10
 triggers:
 - type: rabbitmq
 metadata:
 queueName: inference-requests
 mode: QueueLength
 value: "5"

1

kubectl port-forward -n keda-ai-demo svc/api 8080:8080

1
2
3
4
5
6

for i in $(seq 1 20); do
 curl -s -X POST http://127.0.0.1:8080/tasks \
 -H 'Content-Type: application/json' \
 -d "{\"input\":\"task $i\"}"
 echo
done

1

curl -s http://127.0.0.1:8080/tasks/<task-id>

1

kubectl get pods -n keda-ai-demo -l app=worker -w

1

kubectl logs -n keda deploy/keda-operator -f | grep -E "Scale|scale"

1
2
3

Successfully updated ScaleTarget: Original Replicas Count: 0, New Replicas Count: 1
Successfully updated ScaleTarget: Original Replicas Count: 1, New Replicas Count: 4
Successfully set ScaleTarget replicas count to ScaledObject minReplicaCount: Original Replicas Count: 4, New Replicas Count: 0

1

kubectl delete namespace keda-ai-demo

1
2
3
4
5

# 设置外部 IP
kcctl set cluster my-cluster --external-ip 10.0.0.100

# 设置外部域名
kcctl set cluster my-cluster --external-domain k8s.example.com

1
2
3
4
5
6
7
8

# 通过集群名称查看操作记录
kcctl operation list -c my-cluster

# TUI 模式查看集群操作日志
kcctl operation logs -c my-cluster

# 查看指定操作的详细日志
kcctl operation logs <OPERATION_ID> --follow

1
2
3
4
5
6
7
8

# 查看操作详情
kcctl operation describe <OPERATION_ID>

# 重试失败的操作
kcctl operation retry <OPERATION_ID>

# 终止运行中的操作
kcctl operation terminate <OPERATION_ID>

1
2
3
4
5

# 下载最新版本的 kcctl
curl -sfL https://oss.kubeclipper.io/get-kubeclipper.sh | KC_REGION=cn bash -

# 验证安装
kcctl version

1
2

root@lixd-dev-3:~# kcctl version
kcctl version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.0", GitCommit:"2561b625224a9cfd30941190bd38b828dc0ef1bb", GitTreeState:"clean", BuildDate:"2026-06-02T09:05:33Z", GoVersion:"go1.24.2", Compiler:"gc", Platform:"linux/amd64"}

1
2
3
4
5

# 对于 aio 环境使用 kcctl deploy 即可完成部署
kcctl deploy

# 更多参数参考 kcctl deploy -h
# kcctl deploy --server $IPADDR_SERVER --agent $IPADDR_AGENT --pk-file /root/.ssh/id_rsa --pkg $PKG --ip-detect=interface=ens3 --v 5 

1
2
3
4
5
6
7
8

 _ __ _ _____ _ _
| | / / | | / __ \ (_)
| |/ / _ _| |__ ___| / \/ |_ _ __ _ __ ___ _ __
| \| | | | '_ \ / _ \ | | | | '_ \| '_ \ / _ \ '__|
| |\ \ |_| | |_) | __/ \__/\ | | |_) | |_) | __/ |
\_| \_/\__,_|_.__/ \___|\____/_|_| .__/| .__/ \___|_|
 | | | |
 |_| |_|

1
2
3
4
5
6

root@lixd-dev-3:~# kcctl get node
+--------------------------------------+------------+---------+----------------+-------------+-----+---------+
| ID | HOSTNAME | REGION | IP | OS/ARCH | CPU | MEM |
+--------------------------------------+------------+---------+----------------+-------------+-----+---------+
| d6dff191-9a79-49bb-95fb-69c733c9fe7f | lixd-dev-3 | default | 172.16.131.146 | linux/amd64 | 8 | 15991Mi |
+--------------------------------------+------------+---------+----------------+-------------+-----+---------+

1
2
3
4
5
6
7
8
9

root@lixd-dev-3:~# kcctl create cluster --name demo --master 172.16.131.146 --untaint-master
[2026-06-02T09:47:29Z][INFO] use default containerd version 2.2.4
[2026-06-02T09:47:29Z][INFO] use default calico version v3.31.5
[2026-06-02T09:47:29Z][INFO] use default k8s version v1.36.1
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+
| NAME | REGION | MASTER COUNT | WORKER COUNT | STATUS | APISERVER CERTS EXPIRATION | CREATE TIMESTAMP |
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+
| demo | default | 1 | 0 | Installing | | 2026-06-02 09:47:29 +0000 UTC |
+------+---------+--------------+--------------+------------+----------------------------+-------------------------------+

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

root@lixd-dev-3:~# kcctl operation list -c demo
+--------------------------------------+---------+---------------+---------+---------------------------+---------------------+-------+
| ID | CLUSTER | NAME | STATUS | SPONSOR | CREATED AT | STEPS |
+--------------------------------------+---------+---------------+---------+---------------------------+---------------------+-------+
| 40bee830-6ff5-4ed9-b07f-47762e0055a8 | demo | CreateCluster | running | https-172.16.131.146-8080 | 2026-06-02 09:47:29 | 14 |
+--------------------------------------+---------+---------------+---------+---------------------------+---------------------+-------+
root@lixd-dev-3:~# kcctl operation logs -c demo
root@lixd-dev-3:~# kcctl operation logs 40bee830-6ff5-4ed9-b07f-47762e0055a8

───── Step: installRuntime (c11db224-d4bf-49a5-8fbb-4e3e8fc10490) [successful] 2026-06-02 09:47:29 ─────
 successful lixd-dev-3 (172.16.131.146) d6dff191-9a79-49bb-95fb-69c733c9fe7f [3s]
 [2026-06-02T09:47:29Z] + download from http://172.16.131.146:8081/containerd/2.2.4/amd64/manifest.json

 [2026-06-02T09:47:29Z] + download from http://172.16.131.146:8081/containerd/2.2.4/amd64/config... (truncated)

───── Step: nodeEnvSetup (f5c78839-4840-490b-a055-5d5f51f6ad4b) [successful] 2026-06-02 09:47:32 ─────
 successful lixd-dev-3 (172.16.131.146) d6dff191-9a79-49bb-95fb-69c733c9fe7f [1s]
 [2026-06-02T09:47:32Z] + /bin/bash -c
 systemctl stop firewalld || true
 systemctl disable firewalld || true
 setenforce 0
 sed -i s/^SELINUX=.*$/SELINUX=disabled/ /etc/selinux/config
 modprobe br_netfilt... (truncated)

───── Step: installExtension (97a39913-50ed-41cd-9b67-e476d57b7c7a) [successful] 2026-06-02 09:47:32 ─────
 successful lixd-dev-3 (172.16.131.146) d6dff191-9a79-49bb-95fb-69c733c9fe7f [33s]
 [2026-06-02T09:47:32Z] + download from http://172.16.131.146:8081/k8s-extension/v1/amd64/manifest.json

 [2026-06-02T09:47:32Z] + download from http://172.16.131.146:8081/k8s-extension/v1/amd64/config... (truncated)

1

kcctl operation logs -c demo

1
2
3
4
5
6
7
8

root@lixd-dev-3:~# kubectl get cs
NAME STATUS MESSAGE ERROR
scheduler Healthy ok
controller-manager Healthy ok
etcd-0 Healthy ok
root@lixd-dev-3:~# kubectl get node -owide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
lixd-dev-3 Ready control-plane 4m16s v1.36.1 172.16.131.146 <none> Ubuntu 24.04.3 LTS 6.8.0-90-generic (amd64) containerd://2.2.4

1
2

# openspec
npm install -g @fission-ai/openspec@latest

1

openspec init

1
2

# /opsx:propose "your idea"
/opsx:propose "创建一个 Todo 应用"

1
2

# /openspec:apply $proposal
/opsx:apply

1
2

# /opsx:archive $proposal
/opsx:archive add-task-priority

1
2
3

# 在 claude code 终端执行
/plugin marketplace add https://github.com/obra/superpowers-marketplace.git
/plugin install superpowers@superpowers-marketplace

1
2
3
4
5
6
7

/opsx:propose "创建一个单页网页版Todo应用。它必须包含以下核心功能：
1. 一个输入框和一个'添加'按钮，用于创建新任务。
2. 每个任务项显示为一行，包含任务文本。
3. 每个任务项前有一个复选框，点击可将任务标记为'已完成'（视觉上需有区分，如删除线）。
4. 每个任务项旁有一个'删除'按钮，点击可移除该任务。
5. 所有任务数据必须在浏览器刷新后依然保留（使用localStorage）。
额外要求：代码结构应清晰，便于未来添加'筛选'或'优先级'等功能。"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

⏺ 所有产物已创建。以下是总结：

 变更：web-todo-app
 位置：openspec/changes/web-todo-app/

 已创建产物：
 - proposal.md — 动机：浏览器原生 Todo 应用，具备 localStorage
 持久化功能，可作为未来扩展（筛选、优先级）的基础
 - design.md — 技术方法：原生 JS，3 文件结构（index.html + style.css +
 app.js），集中状态与显式重渲染周期，时间戳 ID
 - specs/ — 3 个能力规范：
 - task-management — 创建、切换完成状态、删除任务
 - task-persistence — localStorage 保存/加载，处理损坏数据
 - task-ui — 输入表单、任务列表渲染（删除线已完成）、空状态、键盘支持
 - tasks.md — 8 组共 21 个实现任务，涵盖项目结构 → 集成验证

 所有产物已创建！已准备好进行实现。运行 /opsx:apply 以开始实现。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

读取以下 OpenSpec change 文件（必须完整读取，不要摘要）：
- openspec/changes/<change-name>/proposal.md
- openspec/changes/<change-name>/design.md
- openspec/changes/<change-name>/tasks.md
- openspec/changes/<change-name>/specs/ 下所有 spec.md（如有）

然后使用 superpowers 进行头脑风暴，深度技术设计，并传入以下上下文：

---
Change: <change-name>
上游需求（来自 OpenSpec，不要重写）：
- 目标：<从 proposal.md 提取>
- 架构约束：<从 design.md 提取>
- 任务边界：<从 tasks.md 提取>

约束：
1. OpenSpec 是需求的事实源，不要重新定义需求，不要重写 proposal/spec
2. 你的任务是基于已有需求做深度技术设计：实现方案、技术风险、测试策略、边界条件
3. 如发现 delta spec 缺少验收场景，只能回写 OpenSpec delta spec，不要在 Design Doc 中创建第二份需求 spec
4. 跳过上下文探索，直接进入设计提问
---

完成后产出：
- Design Doc → docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 （frontmatter 包含：change: <change-name>, role: technical-design, canonical_spec: openspec）
- delta spec 补充（如有）→ openspec/changes/<change-name>/specs/<capability>/spec.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

产出完成。

 Design Doc → docs/superpowers/specs/2026-05-26-web-todo-app-design.md
 - 7 个章节：实现方案（状态流、ID 生成、持久化、渲染策略、事件委托、添加流程、存储告警）、技术风
险矩阵、测试策略、边界条件表、扩展性分析

 Delta Spec 补充 → 回写到 OpenSpec 三个 spec 文件，新增 5 个缺失场景：

 ┌──────────────────┬──────────────────────────┬──────────────────────────────────┐
 │ Spec │ 新增场景 │ 原因 │
 ├──────────────────┼──────────────────────────┼──────────────────────────────────┤
 │ task-management │ whitespace-only 输入拒绝 │ "empty" 定义不完整 │
 ├──────────────────┼──────────────────────────┼──────────────────────────────────┤
 │ task-persistence │ localStorage 写入失败 │ 隐私模式/配额是真实故障路径 │
 ├──────────────────┼──────────────────────────┼──────────────────────────────────┤
 │ task-persistence │ 部分有效数据恢复 │ 单条损坏不应导致整个列表丢失 │
 ├──────────────────┼──────────────────────────┼──────────────────────────────────┤
 │ task-ui │ 渲染 HTML/script 内容 │ XSS 是安全关键边界 │
 ├──────────────────┼──────────────────────────┼──────────────────────────────────┤
 │ task-ui │ Enter 键空输入拒绝 │ 键盘路径需要与按钮路径相同的守卫 │
 └──────────────────┴──────────────────────────┴──────────────────────────────────┘

 关键技术决策摘要：
 - 渲染：DOM API (createElement + textContent)，绝不用 innerHTML — 从根本上防止 XSS
 - 事件：事件委托（dataset.action 派发）— 配合 full re-render 模式，避免监听器泄漏
 - ID：Date.now().toString(36) + 随机后缀 — 比纯时间戳更抗碰撞
 - 持久化失败：try/catch + 非阻塞告警横幅，应用在内存中保持正常运行

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

使用 superpowers writing-plans，基于 Design Doc 创建实现计划。

计划要求：
- 保存至 docs/superpowers/plans/YYYY-MM-DD-<feature>.md
- 引用设计文档，拆分为可执行任务
- Plan 文件头必须包含：
 ---
 change: <openspec-change-name>
 design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
 base-ref: <先运行 git rev-parse HEAD 记录当前提交>
 ---

计划创建后：
1. 创建新分支：git checkout -b <change-name>
2. 使用 superpowers subagent-driven-development 执行实现

逐任务实现，每完成一个任务：
1. 在 tasks.md 中勾选（[ ] → [x]）
2. 提交代码，commit message 体现设计意图

实现中发现 spec 不完整时的处理：
- 缺少验收场景/边界条件 → 直接编辑 delta spec + design.md，追加 tasks.md 任务
- 接口变更/新组件/数据流变化 → 重新 superpowers brainstorming 更新 Design Doc
- 全新能力需求 → /opsx:new 创建新的 OpenSpec change
- 新增任务超过初始任务数的 50% → 考虑拆分为新 change

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

⏺ 计划已创建。现在创建分支并提交计划。

⏺ Bash(git checkout -b web-todo-app)
 ⎿ Switched to a new branch 'web-todo-app'

⏺ Bash(git add docs/superpowers/plans/2026-05-26-web-todo-app.md && git commit -m "chore: add
 implementation plan for web-todo-app")
 ⎿ ok 1 file changed, 158 insertions(+)
 ok web-tod

⏺ 现在使用 subagent 驱动的开发来执行实现。每个任务都有一个专门的 agent。我将逐个任务地开始执行。

⏺ 开始执行。T1–T3
 是无依赖的骨架任务，我将按顺序实现它们（它们共享项目上下文，子代理将需要完整设计）。让我从 T1
 开始。

⏺ Agent(T1: Create index.html)
 ⎿ Initializing…

✢ Creating HTML structure… (1m 39s · ↓ 2.8k tokens)
 ⎿ ◼ T1: HTML structure
 ◻ T9: Integration verification
 ◻ T4: State operations + ID generation
 ◻ T5: Persistence layer
 ◻ T8: Completed task styling
 … +4 pending

......
......

 ⏺ 所有9项任务已实现并提交。这是摘要：

 分支：web-todo-app (11 次提交)

 交付物：
 - 实现计划：docs/superpowers/plans/2026-05-26-web-todo-app.md
 - 设计文档：docs/superpowers/specs/2026-05-26-web-todo-app-design.md
 - 增量规范（5个新场景已回写）：
 - task-management：空白输入拒绝
 - task-persistence：写入失败 + 部分有效数据恢复
 - task-ui：XSS 安全渲染 + 回车键空输入保护
 - 应用文件：index.html + style.css + app.js

 应用内关键设计决策：
 - textContent (从不 innerHTML) — XSS 安全
 - 事件委托，通过 dataset.action — 与全量重新渲染兼容，无监听器泄漏
 - generateId() = base-36 时间戳 + 随机后缀 — 碰撞安全
 - try/catch 在 saveTasks() 中 — 隐私浏览/配额失败 → 非阻塞横幅
 - isValidTask() 过滤器在 loadTasks() 中 — 部分损坏不会破坏整个列表

1
2

使用 openspec-verify-change 做完整验证，然后 superpowers 的 finishing-a-development-branch
处理分支。验证不通过则修复。

1

/opsx:archive

1

npm install -g @rpamis/comet

1
2

cd your-project
comet init

1

/comet "帮我实现一个 TODO 应用"

1
2
3
4
5
6

$ /comet "帮我优化 kcctl 中的 operation 和 logs 命令，希望提高日志展示上的可读性"

# 先自动检测当前阶段
- 按照 Comet 流程，先检测活跃 Change 和 Preset。
# 判断，如果是 hotfix、tweak 会走简化流程
- 没有活跃 Change，这不是 hotfix 也不是 tweak（是功能优化改进），需要进入 /comet-open 创建新变更。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 进入第一阶段 open
- 按照 comet-open 流程，先探索问题空间。

⏺ Skill(openspec-explore)
 ⎿  Successfully loaded skill
 
⏺ Bash(openspec new change "improve-kcctl-operation-logs")
 ⎿  - Creating change 'improve-kcctl-operation-logs'...
 ✔ Created change 'improve-kcctl-operation-logs' at openspec/changes/improve-kcctl-operation-logs/ (schema: spec-driven)
 
 ⏺ 设计和规范已就绪，并行创建。
 ⏺ Change 创建完成。现在初始化 comet 状态并运行 open 阶段守卫。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# 进入第二阶段 desgin
Open 阶段完成，自动流转到 design 阶段。继续 /comet-design。

⏺ 交接包已生成。现在进入 brainstorming 阶段做深度技术设计。

⏺ Skill(brainstorming)
 ⎿  Successfully loaded skill

⏺ 我先阅读一下交接上下文，并探究当前的代码库结构。

⏺ Explore(Explore kcctl command patterns)
 ⎿  Done (18 tool uses · 57.7k tokens · 1m 43s)
 (ctrl+o to expand)

✽ Offering visual companion… (5m 47s · ↑ 8.4k tokens)
 ⎿  ✔ Explore project context for operation/logs design
 ◼ Offer visual companion for TUI layout questions
 ◻ Spec self-review
 ◻ Write design doc
 ◻ User reviews spec
 
⏺ 好，先启动了可视化服务器。现在进入第一个设计问题。

 TUI 日志查看界面的布局是核心设计决策。spec 里写的是"步骤列表在左，日志内容在右"的分栏布局，但还有别的可能性。让我用浏览器展示几个布局方案给你比较。
 
⏺ 浏览器里展示了 3 种 TUI 布局方案，请打开 http://localhost:59683 查看：

 - A: Split Panel — 左侧步骤列表，右侧日志内容，点步骤切换日志
 - B: Stacked — 顶部步骤横排，下方日志区，纵向日志空间更大
 - C: Tree View — 树形展开折叠，日志内嵌在步骤下方，最简洁

 看看哪个直觉上最好用？

✻ Sautéed for 1m 19s

❯ 方案 A 

⏺ 设计方案已基本成型，让我整理一下完整设计然后给你确认。


⏺ 好，现在写 Design Doc。
⏺ Design Doc 已写入 docs/superpowers/specs/2026-05-27-kcctl-operation-logs-design.md。请审阅一下，有要改的告诉我，没问题的话我们进入实施计划。

❯ 继续吧

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

⏺ Design 阶段通过，自动流转到 build。现在调用 comet-build。

⏺ Skill(comet-build)
 ⎿  Successfully loaded skill
 
⏺ Step 1: 制定实施计划。
⏺ Step 3: 工作区隔离。这个变更涉及 ~15 个文件（新增 pkg/cli/operation/ 整个目录 + 修改 api.go/root.go/logs.go），推荐创建分支。

⏺ Step 4: 选择执行方式。计划有 20 个任务，跨 5 个 phase，推荐 subagent-driven-development。
执行方式？计划有 20 个任务，跨 5 个 phase，推荐 subagent 模式。

❯ 1. Subagent-driven (Recommended)
 任务独立、复杂度高，子 agent 并行执行 + 双阶段审查。适合 20 个任务的规模
 2. Executing-plans
 任务简单、轻量快速，顺序执行。适合小规模
 3. Type something.
 

⏺ 好的，我现在已经掌握了所有上下文。让我创建任务追踪并开始分派子代理。任务1.1-1.4是小型API客户端的修改，可以作为一个批次处理；2.1-2.5是操作子命令；3.1-3.4是纯文本日志；4.1-4.6是TUI；5.1-5.4是测试
 。

⏺ 开始第一阶段。正在派遣实现者子代理执行 API 客户端扩展。

✢ Implementing API client extensions… (2m 9s · ↓ 3.9k tokens · almost done thinking)
 ⎿  ◼ Phase 1: API Client Extensions (1.1-1.4)
 ◻ Phase 2: Operation Subcommand Framework (2.1-2.5)
 ◻ Phase 3: Operation Logs Plain-Text Mode (3.1-3.4)
 ◻ Phase 4: TUI Log Viewer (4.1-4.6)
 ◻ Phase 5: Tests (5.1-5.4)
....
✽ Pontificating… (42m 30s · ↓ 68.8k tokens · almost done thinking)
 ⎿  Tip: Use /clear to start fresh when switching topics and free up context
 
 
- 所有 5 个阶段都已完成。让我进行最终的构建+测试验证，然后运行构建守卫。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

⏺ Build 阶段全部通过，自动流转到 verify。进入 comet-verify。
⏺ 已评估为完整验证模式。让我再用 base-ref 复核提交区间。

⏺ 所有制品都已完成。现在让我根据完整的验证检查清单手动执行完整的验证。

⏺ 验证发现了 1 个 FAIL 和 2 个 minor 问题。主要问题是 kcctl operation list 缺少 sponsor 列。让我修复。


⏺ 所有验证问题已修复。现在运行收尾流程。

⏺ Skill(finishing-a-development-branch)
 ⎿  Successfully loaded skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

⏺ Verify 阶段通过，自动流转到 archive。进入最后阶段。

⏺ Skill(comet-archive)
 ⎿  Successfully loaded skill
 
⏺ 归档完成，8/8 步骤全部成功。

 brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档 ✓

 Comet 流程全部完成。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

type DeviceInfo struct {
 Name string
 Type string
 Size int64
}

func Discover(devicePath string) ([]DeviceInfo, error) {
 var devices []DeviceInfo

 info, err := os.Stat(devicePath)
 if err != nil {
 if os.IsNotExist(err) {
 klog.Warningf("device path %s does not exist", devicePath)
 return devices, nil
 }
 return nil, fmt.Errorf("stat device path %s failed: %w", devicePath, err)
 }

 err = filepath.WalkDir(devicePath, func(path string, d fs.DirEntry, err error) error {
 // ...遍历目录，每个文件作为一个设备...
 devices = append(devices, DeviceInfo{
 Name: d.Name(),
 Type: "gopher",
 Size: fi.Size(),
 })
 return nil
 })
 return devices, err
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

func BuildDriverResources(nodeName string, devices []DeviceInfo) resourceslice.DriverResources {
 driverDevices := make([]resourceapi.Device, 0, len(devices))

 for _, dev := range devices {
 driverDevices = append(driverDevices, resourceapi.Device{
 Name: dev.Name,
 Attributes: map[resourceapi.QualifiedName]resourceapi.DeviceAttribute{
 resourceapi.QualifiedName(common.DriverName + "/type"): {
 StringValue: ptrTo(dev.Type),
 },
 },
 Capacity: map[resourceapi.QualifiedName]resourceapi.DeviceCapacity{
 resourceapi.QualifiedName(common.DriverName + "/size"): {
 Value: *resource.NewQuantity(dev.Size, resource.DecimalSI),
 },
 },
 })
 }

 return resourceslice.DriverResources{
 Pools: map[string]resourceslice.Pool{
 nodeName: {
 Slices: []resourceslice.Slice{
 {Devices: driverDevices},
 },
 },
 },
 }
}

1
2
3
4
5
6
7

type DRAPlugin interface {
 PrepareResourceClaims(ctx context.Context, claims []*resourceapi.ResourceClaim) (
 map[types.UID]PrepareResult, error)
 UnprepareResourceClaims(ctx context.Context, claims []NamespacedObject) (
 map[types.UID]error, error)
 HandleError(ctx context.Context, err error, msg string)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

func (p *GopherDRAPlugin) PrepareResourceClaims(ctx context.Context,
 claims []*resourceapi.ResourceClaim) (map[types.UID]kubeletplugin.PrepareResult, error) {

 result := make(map[types.UID]kubeletplugin.PrepareResult)

 for _, claim := range claims {
 // 提取已分配的 gopher 设备名称
 deviceNames := p.extractAllocatedDevices(claim)

 // 创建 CDI spec 文件，返回 CDI device ID
 cdiDeviceIDs, err := p.cdiHandler.CreateClaimSpec(
 string(claim.UID), deviceNames)

 // 构建返回结果
 for _, req := range claim.Status.Allocation.Devices.Results {
 if req.Driver == common.DriverName {
 devices = append(devices, kubeletplugin.Device{
 Requests: []string{req.Request},
 PoolName: req.Pool,
 DeviceName: req.Device,
 CDIDeviceIDs: cdiDeviceIDs,
 })
 }
 }

 result[claim.UID] = kubeletplugin.PrepareResult{Devices: devices}
 }
 return result, nil
}

1
2
3
4
5
6
7
8
9

func (p *GopherDRAPlugin) UnprepareResourceClaims(ctx context.Context,
 claims []kubeletplugin.NamespacedObject) (map[types.UID]error, error) {

 result := make(map[types.UID]error)
 for _, claim := range claims {
 result[claim.UID] = p.cdiHandler.DeleteClaimSpec(string(claim.UID))
 }
 return result, nil
}

1
2
3
4
5
6
7

func (p *GopherDRAPlugin) HandleError(ctx context.Context, err error, msg string) {
 if errors.Is(err, kubeletplugin.ErrRecoverable) {
 klog.Warningf("recoverable error: %s: %v", msg, err)
 return
 }
 klog.Fatalf("fatal error: %s: %v", msg, err)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

func (h *Handler) CreateClaimSpec(claimUID string, deviceNames []string) ([]string, error) {
 spec := &cdispec.Spec{
 Kind: h.kind(), // "gopher.example.com/gopher"
 Devices: []cdispec.Device{},
 }

 var cdiDeviceIDs []string
 for _, devName := range deviceNames {
 cdiDeviceName := fmt.Sprintf("%s-%s", claimUID, devName)
 cdiDeviceID := fmt.Sprintf("%s/%s=%s", h.vendor, h.class, cdiDeviceName)
 cdiDeviceIDs = append(cdiDeviceIDs, cdiDeviceID)

 device := cdispec.Device{
 Name: cdiDeviceName,
 ContainerEdits: cdispec.ContainerEdits{
 Env: []string{
 fmt.Sprintf("GOPHER=%s", strings.Join(deviceNames, ",")),
 },
 },
 }
 spec.Devices = append(spec.Devices, device)
 }

 specName := cdiapi.GenerateTransientSpecName(h.vendor, h.class, claimUID)
 return cdiDeviceIDs, h.cache.WriteSpec(spec, specName)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

func main() {
 // 解析参数
 flag.StringVar(&nodeName, "node-name", "", "Node name (or NODE_NAME env)")
 flag.StringVar(&devicePath, "device-path", "/etc/gophers", "Device path")
 flag.DurationVar(&rescanInterval, "rescan-interval", 60*time.Second, "Rescan interval")

 // 创建 k8s 客户端
 cfg, _ := rest.InClusterConfig()
 kubeClient, _ := kubernetes.NewForConfig(cfg)

 // 创建 CDI handler
 cdiHandler, _ := cdi.NewHandler(driverName, "gopher.example.com", "gopher", devicePath)

 // 创建 DRA Plugin
 draPlugin := plugin.NewGopherDRAPlugin(cdiHandler)

 // 启动 DRA Plugin Helper（注册到 kubelet + gRPC server）
 helper, _ := kubeletplugin.Start(ctx, draPlugin,
 kubeletplugin.DriverName(driverName),
 kubeletplugin.KubeClient(kubeClient),
 kubeletplugin.NodeName(nodeName),
 )
 defer helper.Stop()

 // 发现设备并发布 ResourceSlice
 devices, _ := device.Discover(devicePath)
 resources := device.BuildDriverResources(nodeName, devices)
 helper.PublishResources(ctx, resources)

 // 定期 rescan
 go rescanLoop(ctx, helper, nodeName, devicePath, rescanInterval)

 <-ctx.Done()
}

1
2
3
4

cd i-dra-driver
make build-image
# 或
docker build -t docker.io/lixd96/i-dra-driver:latest .

1
2
3

mkdir -p /etc/gophers
echo 'hello from gopher-a' > /etc/gophers/gopher-a
echo 'hello from gopher-b' > /etc/gophers/gopher-b