@sema-agent/server 7.146.0 → 7.148.0

package/deploy/sema-up/lib/flagshape.sh

@@ -22,6 +22,10 @@ FLAG_WORDS_USERS="single multi"
 # 事实核对,kube-up 的 helm values,cluster-up 的渲染清单与 helm values 同调这一只(修前 kube-up 另写一份同义翻译;
 # cluster-up 一份都没有 ⇒ --users=multi 在 --kube=machines 路径上被静默丢成单用户)。只认两词,别的词先过 flag_enum。
 principal_of_users() { [ "$1" = "multi" ] && echo true || echo false; }
+# 租户形 ⇒ 单用户运维声明 OPERATOR_SINGLE_USER 的值(唯一定义;三只脚本 / 渲染段同调):server 装配运维面时要单用户部署说出谁是运维,
+# 不声明不起服(声明与具名名单 OPERATOR_PRINCIPALS 二选一;本工具渲前者)。single = 这台只有一个人 ⇒ 他就是运维(true);
+# multi = 多租,运维由具名名单另给 ⇒ 不声明(false;多租形上声明本身会被 server 拒)。chart 从 server.requirePrincipal 同一句派生。
+operator_single_user_of_users() { [ "$1" = "multi" ] && echo false || echo true; }
 
 # users_decide <显式给了 USERS 吗(1 / 空)> —— kube 两条装配路径(kube-up / cluster-up)的租户形决策,与 sema-up 的
 # compose 档同一条规则:**决策 = 显式 USERS ∨ 上一次落在 $ENVF 的部署事实 REQUIRE_PRINCIPAL ∨ single**;显式值与事实

package/deploy/sema-up/lib/health.sh

@@ -1,13 +1,40 @@
-# lib/health.sh — 「装好的引擎 /health 体说它真落在哪个后端」的唯一读法 + sema-up 部署的期望值。
+# lib/health.sh — 「装好的引擎 /health 体说它落在哪个后端、店活不活得过替换」的唯一读法 + sema-up 部署的期望值。
 # smoke.sh / kube-up.sh / cluster-up.sh 三处验收都调它,不各写一份(各写一份的下场:有一处还只看 HTTP 200,把退到内存的服务判绿)。
 #
 # 事实(出处是引擎,不是推测):
-#  · `/health` 体里的 `sessionBackend` 是**装配后**的有效店:`durable(<kind>)`(kind = pg | mysql | local)或 `memory`
-#    (引擎侧只有一只读法:src/store-posture.ts 的 `sessionStoreLabelOf`);
+#  · `/health` 体里的 `sessionBackend` = 会话店**装配后**落在哪种后端:`pg` | `mysql` | `local` | `memory`(只说种类;
+#    引擎侧只有一只读法:src/store-posture.ts 的 `sessionStoreLabelOf`);
+#  · `/health` 体里的 `store.durability` = 店活不活得过容器 / Pod 替换:`durable` | `ephemeral` | `unknown`(三根取最弱:数据根、
+#    封签钥匙目录、file 记忆根;与 GET /v1/capabilities 的 `store.durability` 同一只读数;逐根明细在 GET /v1/diagnostics/wiring 的 `storeDurability.roots`);
+#  · 这两位只给**出示了服务凭据**的读者:sema-up 部署的引擎一律配了 `SERVICE_AUTH_TOKEN`,而配了服务凭据的引擎对匿名 `/health` 只给存活位与自报位三键
+#    (src/http/health-reader.ts),不给 `sessionBackend` / `store`。三处验收读 `/health` 都带这枚凭据:本机两处(smoke.sh / kube-up.sh)走 `health_curl`,
+#    多机那一处(cluster-up.sh)是同一句话在远端节点上的写法(凭据经 stdin 配置喂 curl,不进远端 argv);
 #  · sema-up 三条路径(compose / kube / 多机)起的引擎一律 `DB_BACKEND=pg`(stack/compose.yaml、chart/templates/server.yaml、
-#    stack/sema-stack-cluster.yaml 逐份写死),所以装好的引擎必须读到 `durable(pg)`。读到 `memory` = 会话 / 停驻 / run 账本在进程内存里、
+#    stack/sema-stack-cluster.yaml 逐份写死),所以装好的引擎必须读到 `sessionBackend=pg`。读到 `memory` = 会话 / 停驻 / run 账本在进程内存里、
 #    重启即丢 —— /health 照样 200、401 门照样在,只有这一位说了实话,验收必须看它。
-SEMA_UP_EXPECT_SESSION_BACKEND="durable(pg)"
+#  · `store.durability` 必须读得到(三词之一;读不到 = 引擎早于这一读法,或体不是引擎的);它不是 `durable` 时验收**照过**、但把读数与指路说出来
+#    (与引擎自己的起服审计同一律:会话店在 pg 上恒持久,别的根判不出 / 易失只 warn)。三条路径都给封签钥匙目录挂了卷,读数随卷的形走:
+#    多机清单的 Longhorn RWX(NFS)读 `durable`;compose 的具名卷 / `--data-root` bind、图表路径上 hostPath 形的存储类(如 local-path)是绑定挂载一只子目录,
+#    判不出它跟着谁走,读 `unknown`。
+SEMA_UP_EXPECT_SESSION_BACKEND="pg"
+
+# health_curl <服务凭据|空串> <curl 实参…> —— 本机读 `/health`:有凭据就带 `Authorization: Bearer`(全键),空串 = 不带(没配服务凭据的引擎本来就给全键)。
+# 凭据只上本机 curl 的实参(与 smoke.sh 的 POST /v1/tasks 同一处境)。
+health_curl() {
+  local tok="$1"; shift
+  if [ -n "$tok" ]; then curl "$@" -H "Authorization: Bearer $tok"; else curl "$@"; fi
+}
+
+# health_curl_config <服务凭据> —— 多机验收在远端节点上读 `/health` 用的 curl 配置行(经 stdin 喂 `curl -K -`,凭据不进远端 argv):
+# 打印 `header = "Authorization: Bearer <凭据>"`,凭据里的反斜杠与双引号按 curl 配置文法转义(原样读回);凭据含控制字符(换行 / 回车 …)⇒ rc 1、不打印 ——
+# 那不是能放进 Authorization 头的值,更不能让它多出一行配置。调用方再过一道 `printf '%q'` 才把这一行放进远端 shell 文本(值是数据,不是代码)。
+health_curl_config() {
+  local t="$1"
+  case "$t" in *[[:cntrl:]]*) return 1 ;; esac
+  t="${t//\\/\\\\}"
+  t="${t//\"/\\\"}"
+  printf 'header = "Authorization: Bearer %s"' "$t"
+}
 
 # health_session_backend <health 体> → 打印 `sessionBackend` 的值;体读不成 JSON / 没有这一位 ⇒ 打印空串(调用方按「读不出」处置,不猜)。
 health_session_backend() {
@@ -19,15 +46,37 @@ except Exception:
   print("")' 2>/dev/null
 }
 
-# health_backend_check <health 体> → 0 = 落在期望的后端;1 = 不是(stdout 打一句人话,供调用方拼进失败行)。
+# health_store_durability <health 体> → 打印 `store.durability`(三词之一);体读不成 JSON / 没有这一位 / 不是三词之一 ⇒ 打印空串。
+health_store_durability() {
+  printf '%s' "$1" | python3 -c 'import json,sys
+try:
+  s = json.load(sys.stdin).get("store", {})
+  v = s.get("durability", "") if isinstance(s, dict) else ""
+  print(v if v in ("durable", "ephemeral", "unknown") else "")
+except Exception:
+  print("")' 2>/dev/null
+}
+
+# health_backend_check <health 体> → 0 = 落在期望的后端且读得到持久性(stdout:持久性不是 `durable` 时一句读数 + 指路,调用方拼进成功行);
+# 1 = 不是(stdout 打一句人话,供调用方拼进失败行)。
 health_backend_check() {
-  local got
+  local got dur
   got="$(health_session_backend "$1")"
-  if [ "$got" = "$SEMA_UP_EXPECT_SESSION_BACKEND" ]; then return 0; fi
-  if [ -z "$got" ]; then
-    printf '/health 体里读不出 sessionBackend(期望 %s)' "$SEMA_UP_EXPECT_SESSION_BACKEND"
-  else
-    printf '/health.sessionBackend=%s,期望 %s' "$got" "$SEMA_UP_EXPECT_SESSION_BACKEND"
+  dur="$(health_store_durability "$1")"
+  if [ "$got" != "$SEMA_UP_EXPECT_SESSION_BACKEND" ]; then
+    if [ -z "$got" ]; then
+      printf '/health 体里读不出 sessionBackend(期望 %s)' "$SEMA_UP_EXPECT_SESSION_BACKEND"
+    else
+      printf '/health.sessionBackend=%s,期望 %s' "$got" "$SEMA_UP_EXPECT_SESSION_BACKEND"
+    fi
+    return 1
+  fi
+  if [ -z "$dur" ]; then
+    printf '/health 体里读不出 store.durability(期望 durable / ephemeral / unknown 之一;读不到多半是旧镜像)'
+    return 1
+  fi
+  if [ "$dur" != "durable" ]; then
+    printf 'store.durability=%s(至少一根活不过容器替换或判不出;逐根看 GET /v1/diagnostics/wiring 的 storeDurability.roots,给那只目录挂持久卷)' "$dur"
   fi
-  return 1
+  return 0
 }

package/deploy/sema-up/lib/helm-values-cluster.py

@@ -0,0 +1,18 @@
+import json, os
+e = os.environ
+# json 是合法 yaml;json.dumps 对任意凭据字符安全(引号/反斜杠/换行都正确转义)
+print(json.dumps({
+  "pg": {"instances": int(e["V_PG_INSTANCES"]), "antiAffinity": e["V_PG_AA"]},
+  "minio": {"rootPassword": e["V_MINIO_PW"]},
+  "server": {
+    "image": e["V_SERVER_IMAGE"], "pullPolicy": e["V_PULL_POLICY"],
+    "replicas": int(e["V_REPLICAS"]), "serviceAuthToken": e["V_SVC_TOKEN"],
+    "modelGatewayBaseurl": e["V_MODEL_GATEWAY"], "modelId": e["V_MODEL_ID"],
+    "modelApiKey": e["V_MODEL_KEY"], "sandboxPkgSource": e["V_PKG_SOURCE"],
+    "requirePrincipal": e["V_REQ_PRINCIPAL"],
+  },
+  # chart 0.3.0 起 registry.enabled 默认 true(单机档语义)——machines 多机路径的 registry/git
+  # 面还没接线,必须显式关,不然 helm 撞 registry.image required(2026-07-12 自查)
+  "registry": {"enabled": False},
+  "gitea": {"enabled": False},
+}))

package/deploy/sema-up/lib/helm-values-kube.py

@@ -0,0 +1,35 @@
+import json, os
+e = os.environ
+# json 是合法 yaml;json.dumps 对任意凭据字符安全(引号/反斜杠/换行都正确转义)
+v = {
+  # helm 的 values 合并是深合并——只给部分 parameters 时 values.yaml 里 3 机 as-built 的
+  # shared_buffers=8GB/effective_cache_size=86GB 会留下来,小集群 PG 直接起不来(内存不够)。
+  # 必须整组显式覆盖成保守值;真按机器规格调优的入口是 STORAGE/PG 显式 values(后续档)。
+  "pg": {"instances": int(e["V_PG_INSTANCES"]), "antiAffinity": e["V_PG_AA"],
+         "storageClass": e["V_SC"], "storageSize": "20Gi",
+         "parameters": {"shared_buffers": "256MB", "effective_cache_size": "1GB",
+                        "maintenance_work_mem": "128MB", "random_page_cost": "1.1",
+                        "effective_io_concurrency": "200", "checkpoint_completion_target": "0.9",
+                        "max_parallel_workers": "2"}},
+  "minio": {"rootPassword": e["V_MINIO_PW"], "storageClass": e["V_SC"], "storageSize": "20Gi"},
+  "server": {
+    "image": e["V_SERVER_IMAGE"], "replicas": int(e["V_REPLICAS"]),
+    "serviceAuthToken": e["V_SVC_TOKEN"], "modelGatewayBaseurl": e["V_MODEL_GATEWAY"],
+    "modelId": e["V_MODEL_ID"], "modelApiKey": e["V_MODEL_KEY"],
+    "sandboxPkgSource": e["V_PKG_SOURCE"], "requirePrincipal": e["V_REQ_PRINCIPAL"],
+  },
+  "sandbox": {"runtimeClass": e["V_RT_CLASS"],
+              "networkPolicy": {"nodeCidrs": json.loads(e["V_NODE_CIDRS"])}},
+  "registry": {"enabled": e["V_REG_ENABLED"] == "true", "image": e["V_REG_IMAGE"],
+               "storageClass": e["V_SC"], "adminPassword": e["V_REG_PW"],
+               "sessionSecret": e["V_REG_SS"], "pullToken": e["V_REG_PT"],
+               "giteaBaseUrl": e["V_GITEA_URL"], "giteaOauthClientId": e["V_OA_ID"],
+               "giteaOauthClientSecret": e["V_OA_SECRET"]},
+  "gitea": {"enabled": e["V_GITEA_ENABLED"] == "true", "image": e["V_GITEA_IMAGE"],
+            "storageClass": e["V_SC"], "domain": e["V_NODE_IP"]},
+  # 钥匙卷的存储类:kube-up 按 lib/chart-run.sh sealed_key_class 定(新建 = STORAGE_CLASS;已在 = 它建好时的类,不可改)。其余 sealedKey 键照图表缺省。
+  "sealedKey": {"persistence": {"storageClass": e["V_SK_SC"]}},
+}
+# MinIO 镜像:给了才递(默认只在 chart values.yaml 写一处,不在脚本里再抄一份);国内源 = 整条引用
+if e["V_MINIO_IMAGE"]: v["minio"]["image"] = e["V_MINIO_IMAGE"]
+print(json.dumps(v))

package/deploy/sema-up/lib/lanes.json

@@ -5,8 +5,7 @@
       "choice": "host",
       "users": ["single"],
       "env": {
-        "REMOTE_EXEC": "host",
-        "REQUIRE_EXECUTION_LANE": "true"
+        "REMOTE_EXEC": "host"
       },
       "isolation": "unsupported",
       "note": "server 容器本身就是沙箱:agent 的手落在这只容器里(worktree 隔离在、OS 级隔离不在)。只给单用户 —— 多租户下一个租户的输入会把手指向另一个租户的文件与进程。"
@@ -17,7 +16,6 @@
       "users": ["single", "multi"],
       "env": {
         "REMOTE_EXEC": "e2b",
-        "REQUIRE_EXECUTION_LANE": "true",
         "E2B_API_KEY": null
       },
       "isolation": "supported",
@@ -29,12 +27,11 @@
       "users": ["single", "multi"],
       "env": {
         "REMOTE_EXEC": "k8s",
-        "REQUIRE_EXECUTION_LANE": "true",
         "K8S_SANDBOX_IMAGE": null,
         "K8S_NAMESPACE": null
       },
       "isolation": "supported",
-      "note": "kube 路径**不选词**:runtime 由 kube-up.sh 按 runtimeClass `kata-qemu` 在不在自动定(在 ⇒ kata VM,不在 ⇒ runc 容器),沙箱镜像与沙箱命名空间由 chart/清单给。本行只为对表(能力表 / 必需键 / REQUIRE_EXECUTION_LANE 三面),不进 --sandbox 词表。"
+      "note": "kube 路径**不选词**:runtime 由 kube-up.sh 按 runtimeClass `kata-qemu` 在不在自动定(在 ⇒ kata VM,不在 ⇒ runc 容器),沙箱镜像与沙箱命名空间由 chart/清单给。本行只为对表(能力表 / 必需键两面),不进 --sandbox 词表。"
     }
   ],
   "retired": [

package/deploy/sema-up/lib/regcred.py

@@ -0,0 +1,8 @@
+import base64, json, os
+u, p = os.environ["IPS_USER"], os.environ["IPS_TOKEN"]
+cfg = {"auths": {os.environ["IPS_REG"]: {"username": u, "password": p,
+       "auth": base64.b64encode(f"{u}:{p}".encode()).decode()}}}
+b64 = base64.b64encode(json.dumps(cfg).encode()).decode()
+print(json.dumps({"apiVersion": "v1", "kind": "Secret", "type": "kubernetes.io/dockerconfigjson",
+      "metadata": {"name": "sema-regcred", "namespace": os.environ["IPS_NS"]},
+      "data": {".dockerconfigjson": b64}}))

package/deploy/sema-up/lib/remote/helm-install.sh

@@ -0,0 +1,3 @@
+set -e
+command -v helm >/dev/null && exit 0
+curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash >/dev/null

package/deploy/sema-up/lib/remote/image-import.sh

@@ -0,0 +1,6 @@
+set -e
+trap 'rm -f /tmp/sema-server-image.tar.upload /tmp/sema-server-image.tar' EXIT
+f=/tmp/sema-server-image.tar.upload
+case "$(head -c2 "$f" | od -An -tx1 | tr -d ' ')" in 1f8b) gunzip -c "$f" > /tmp/sema-server-image.tar && f=/tmp/sema-server-image.tar ;; esac
+k3s ctr images import "$f" >/dev/null
+k3s ctr images ls | grep -q sema-server

package/deploy/sema-up/lib/remote/machine-precheck.sh

@@ -0,0 +1,11 @@
+set -e
+command -v curl >/dev/null || { echo "FAIL curl 缺失——建议:apt-get install -y curl"; exit 1; }
+[ "$(uname -m)" = "x86_64" ] || [ "$(uname -m)" = "aarch64" ] || { echo "FAIL 架构 $(uname -m) 不支持——建议:x86_64/aarch64 机器"; exit 1; }
+ram=$(awk '/MemTotal/{printf "%d", $2/1024}' /proc/meminfo)
+[ "$ram" -ge 8192 ] || { echo "FAIL 内存 ${ram}MB < 8G——建议:full-cluster 节点至少 8G(数据面+沙箱同机)"; exit 1; }
+disk=$(df -m / | awk 'NR==2{print $4}')
+[ "$disk" -ge 40960 ] || { echo "FAIL 根盘可用 ${disk}MB < 40G——建议:Longhorn/镜像要空间,清盘或换机"; exit 1; }
+[ -e /dev/kvm ] || echo "WARN 无 /dev/kvm——kata VM 沙箱在本节点不可用(建议:开嵌套虚拟化/裸机;或全集群改 e2b lane)"
+# 钥匙卷是 ReadWriteMany(多副本共用一份钥匙);Longhorn 的 RWX 由节点上的 NFS 客户端挂载 —— 缺它 server Pod 挂不上卷、rollout 等不到就绪
+{ [ -x /sbin/mount.nfs ] || [ -x /usr/sbin/mount.nfs ]; } || echo "WARN 无 NFS 客户端(mount.nfs)——server 的钥匙卷(ReadWriteMany)在本节点挂不上(建议:apt-get install -y nfs-common / yum install -y nfs-utils)"
+hostname

package/deploy/sema-up/lib/remote/region-probe.sh

@@ -0,0 +1,3 @@
+a=$(curl -m3 -so /dev/null -w '%{time_total}' https://mirrors.aliyun.com 2>/dev/null || echo 99)
+b=$(curl -m3 -so /dev/null -w '%{time_total}' https://registry.npmjs.org 2>/dev/null || echo 99)
+awk -v a="$a" -v b="$b" 'BEGIN{print (a<b)?"cn":"global"}'

package/deploy/sema-up/lib/remote/stack-ready.sh

@@ -0,0 +1,26 @@
+set -e
+BUCKETS=("$@")   # 要建的桶(local/<桶>):清单只在 lib/buckets.sh 一处,经位置参数递给远端
+# runner token 跨 ns 复制要赶在 server 起 pod 前(晚了=CreateContainerConfigError 干等——真踩);
+# SA token secret 由控制器异步填充,先等它有值
+TOK=""
+for t in $(seq 1 24); do
+  TOK=$(k3s kubectl get secret sema-runner-token -n sema-sandbox -o jsonpath='{.data.token}' 2>/dev/null || true)
+  [ -n "$TOK" ] && break; sleep 5
+done
+[ -n "$TOK" ] || { echo "sema-runner-token 未被控制器填充" >&2; exit 1; }
+k3s kubectl create secret generic sema-runner-token-copy -n sema --from-literal=token="$(printf '%s' "$TOK" | base64 -d)" \
+  --dry-run=client -o yaml | k3s kubectl apply -f - >/dev/null
+# MinIO 建桶(备份桶+引擎桶)—— 排在等 PG healthy 与等 server rollout **之前**:引擎起服会核快照桶在不在,桶缺时 server 不就绪、rollout 永远等不到,而建桶又排在它后面 ⇒ 互等;
+# MinIO 不依赖 PG,建桶也就不必陪着等 PG(冷启拉镜像 + init 可要几分钟,会把引擎的等桶窗耗掉)
+k3s kubectl rollout status deployment/sema-minio -n sema --timeout=300s >/dev/null
+PW=$(k3s kubectl get secret sema-minio -n sema -o jsonpath='{.data.rootPassword}' | base64 -d)
+k3s kubectl exec deploy/sema-minio -n sema -- sh -c \
+  "mc alias set local http://localhost:9000 sema '$PW' >/dev/null && mc mb --ignore-existing ${BUCKETS[*]}" >/dev/null
+# PG healthy(冷启拉镜像+init 可要几分钟)
+for t in $(seq 1 120); do
+  s=$(k3s kubectl get cluster sema-pg -n sema -o jsonpath='{.status.phase}' 2>/dev/null || true)
+  [ "$s" = "Cluster in healthy state" ] && break; sleep 5
+done
+[ "$s" = "Cluster in healthy state" ] || { k3s kubectl get cluster -n sema; echo "PG 未达 healthy" >&2; exit 1; }
+k3s kubectl rollout status deployment/sema-server -n sema --timeout=300s >/dev/null
+echo STACK_OK

package/deploy/sema-up/lib/remote/vxlan-guard.sh

@@ -0,0 +1,8 @@
+set -e
+iface="$1"
+printf '%s\n' '[Unit]' 'Description=Drop flannel VXLAN on public iface (sema isolation invariant)' \
+  'After=network-online.target k3s.service' '[Service]' 'Type=oneshot' 'RemainAfterExit=yes' \
+  "ExecStart=/bin/sh -c 'iptables -C INPUT -i $iface -p udp --dport 8472 -j DROP 2>/dev/null || iptables -I INPUT -i $iface -p udp --dport 8472 -j DROP'" \
+  '[Install]' 'WantedBy=multi-user.target' > /etc/systemd/system/sema-vxlan-guard.service
+systemctl daemon-reload && systemctl enable --now sema-vxlan-guard.service
+iptables -C INPUT -i "$iface" -p udp --dport 8472 -j DROP

package/deploy/sema-up/lib/render-stack.py

@@ -0,0 +1,17 @@
+import os, sys
+MAP = {"__MINIO_PW__":"R_MINIO_PW", "__SVC_TOKEN__":"R_SVC_TOKEN", "__MODEL_KEY__":"R_MODEL_KEY",
+       "__MODEL_GATEWAY__":"R_MODEL_GATEWAY", "__MODEL_ID__":"R_MODEL_ID",
+       "__SERVER_IMAGE__":"R_SERVER_IMAGE", "__SERVER_PULL_POLICY__":"R_PULL_POLICY",
+       "__PKG_SOURCE__":"R_PKG_SOURCE", "__PG_INSTANCES__":"R_PG_INSTANCES",
+       "__PG_ANTI_AFFINITY__":"R_PG_AA", "__SERVER_REPLICAS__":"R_REPLICAS",
+       "__REQUIRE_PRINCIPAL__":"R_REQ_PRINCIPAL", "__OPERATOR_SINGLE_USER__":"R_OPERATOR_SINGLE_USER"}
+t = open(sys.argv[1], encoding="utf-8").read()
+for ph, env in MAP.items():
+    v = os.environ.get(env)
+    if v is None: raise SystemExit(f"渲染缺 {env}({ph})")
+    if any(c in v for c in "\n\"\\"): raise SystemExit(f"{env} 含 YAML 危险字符(换行/引号/反斜杠)")
+    t = t.replace(ph, v)
+import re
+left = sorted(set(re.findall(r"__[A-Z_]+__", t)))
+if left: raise SystemExit(f"未渲染占位符残留: {left}")
+sys.stdout.write(t)

package/deploy/sema-up/lib/shell-text.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# shell-text.sh —— 把一段文本「按行 / 按词 / 按分隔字符」读进变量的三只函数(被 source,不单独执行)。
+#
+# ── 为什么有这只 lib ─────────────────────────────────────────────────────────────────────────────────────────────────
+# `read … ` 与 `while read …; done` 后面接 here-string(把一段文本直接当输入的那种写法)时,靠 bash 先把整段文本写进一根管道、读者随后才读。
+# 全机管道配额吃紧时,内核只给新管道很小的缓冲(事故里读到的形:512 B),文本一长就写不完,链路停在本机、日志里什么也没有。
+# registry 的一行读数里装着本包的全部版本号(几 KB),恰是这一类。这条死法与脚本逻辑无关,只与「脚本里有没有 here-document / here-string」有关,
+# 所以发车链的两个脚本目录与部署脚本目录(deploy/ 下全部 .sh)的每一行都不许有这两种写法(由仓内测试逐行钉住);
+# 要把一段文本读进变量,走这里:全程只用参数展开,不开管道、不开文件描述符、不起子进程,更不起子 shell(变量赋值与 `return` 留在调用方的 shell 里)。
+# 本文件有两份逐字节相同的拷贝:发车链用的一份在 scripts/lib/,随部署包落到运维机的一份在 deploy/sema-up/lib/(部署目录要能脱离 scripts/ 单独落机)。改一处必须同改另一处,仓内测试逐字节比。
+#
+# ── 三只函数 ────────────────────────────────────────────────────────────────────────────────────────────────────────
+#   text_words <文本> <变量名>…        = `read -r <变量名>…` 读 here-string 的文本:只读文本的第一行,按空格 / 制表切词;
+#                                       前 N-1 个词依次给前 N-1 个变量,第 N 个变量拿剩下的整段(去掉两头的空白);词不够 ⇒ 余下的变量写空串。
+#                                       分隔符取自 IFS 里的空格与制表(IFS 没设 ⇒ 默认,两者都是;`IFS=' ' text_words …` ⇒ 只认空格)。
+#                                       IFS 里有空格 / 制表 / 换行之外的字符,或一个空格与制表都没有 ⇒ rc 2、stderr 一句(不静默换一种切法)。
+#   text_split <分隔字符> <文本> <变量名>…   = `IFS=<分隔字符> read -r <变量名>…` 读 here-string 的文本:只读文本的第一行;分隔字符是单个字符(不是空格 / 制表 / 换行),
+#                                       每个分隔字符都切一刀、空段照留;前 N-1 段依次给前 N-1 个变量,第 N 个变量拿剩下的整段(其中还有分隔字符就原样留着),
+#                                       例外一处与 read 一致:剩下的整段里只有末尾恰一个分隔字符、别无他个 ⇒ 那一个算终结符、不算内容;段不够 ⇒ 余下的变量写空串。
+#   text_pop_line <存余变量名> <行变量名>   从名为 <存余变量名> 的变量里削下第一行放进 <行变量名>,<存余变量名> 留剩下的;存余为空 ⇒ rc 1(没有行了)。
+#                                       逐行遍历的写法(同 `while IFS= read -r l; do …; done` 读 here-string 的文本):
+#                                           rest="$文本"$'\n'            # here-string 在文本末尾补的那个换行;空文本 ⇒ 恰好读到一行空行
+#                                           while text_pop_line rest line; do …; done
+# 变量名只许是调用方的普通变量名(printf -v 写它);本文件的内部变量一律 _ts_ 起头,调用方别用这个前缀。
+# bash 3.2 兼容(发车机 /bin/bash 可能是它):不用关联数组 / mapfile / nameref。
+
+_TS_NL=$'\n'
+_TS_TAB=$'\t'
+
+text_words() { # <文本> <变量名>…
+  [ "$#" -ge 2 ] || { echo "text_words: 用法 text_words <文本> <变量名>…" >&2; return 2; }
+  local _ts_ifs _ts_ws="" _ts_rest _ts_lead _ts_word _ts_tail
+  if [ -z "${IFS+x}" ]; then _ts_ifs=" $_TS_TAB$_TS_NL"; else _ts_ifs="$IFS"; fi
+  [ -z "${_ts_ifs//[ $_TS_TAB$_TS_NL]/}" ] || { echo "text_words: IFS 里有空格 / 制表 / 换行以外的字符,不支持" >&2; return 2; }
+  case "$_ts_ifs" in *" "*) _ts_ws=" " ;; esac
+  case "$_ts_ifs" in *"$_TS_TAB"*) _ts_ws="$_ts_ws$_TS_TAB" ;; esac
+  [ -n "$_ts_ws" ] || { echo "text_words: IFS 里既没有空格也没有制表,没有可切的分隔符" >&2; return 2; }
+  _ts_rest="${1%%"$_TS_NL"*}"
+  shift
+  while [ "$#" -gt 1 ]; do
+    _ts_lead="${_ts_rest%%[!$_ts_ws]*}"
+    _ts_rest="${_ts_rest#"$_ts_lead"}"
+    _ts_word="${_ts_rest%%[$_ts_ws]*}"
+    _ts_rest="${_ts_rest#"$_ts_word"}"
+    printf -v "$1" '%s' "$_ts_word" || return 2
+    shift
+  done
+  _ts_lead="${_ts_rest%%[!$_ts_ws]*}"
+  _ts_rest="${_ts_rest#"$_ts_lead"}"
+  _ts_tail="${_ts_rest##*[!$_ts_ws]}"
+  _ts_rest="${_ts_rest%"$_ts_tail"}"
+  printf -v "$1" '%s' "$_ts_rest" || return 2
+}
+
+text_pop_line() { # <存余变量名> <行变量名>
+  [ "$#" -eq 2 ] || { echo "text_pop_line: 用法 text_pop_line <存余变量名> <行变量名>" >&2; return 2; }
+  local _ts_all="${!1}"
+  [ -n "$_ts_all" ] || return 1
+  printf -v "$2" '%s' "${_ts_all%%"$_TS_NL"*}" || return 2
+  case "$_ts_all" in
+    *"$_TS_NL"*) printf -v "$1" '%s' "${_ts_all#*"$_TS_NL"}" || return 2 ;;
+    *) printf -v "$1" '%s' "" || return 2 ;;
+  esac
+}
+
+text_split() { # <分隔字符> <文本> <变量名>…
+  [ "$#" -ge 3 ] || { echo "text_split: 用法 text_split <分隔字符> <文本> <变量名>…" >&2; return 2; }
+  local _ts_sep="$1" _ts_rest="${2%%"$_TS_NL"*}" _ts_field
+  case "$_ts_sep" in
+    " " | "$_TS_TAB" | "$_TS_NL") echo "text_split: 分隔字符不能是空格 / 制表 / 换行(要按空白切词用 text_words)" >&2; return 2 ;;
+  esac
+  [ "${#_ts_sep}" -eq 1 ] || { echo "text_split: 分隔符必须恰是一个字符" >&2; return 2; }
+  shift 2
+  while [ "$#" -gt 1 ]; do
+    _ts_field="${_ts_rest%%"$_ts_sep"*}"
+    case "$_ts_rest" in *"$_ts_sep"*) _ts_rest="${_ts_rest#*"$_ts_sep"}" ;; *) _ts_rest="" ;; esac
+    printf -v "$1" '%s' "$_ts_field" || return 2
+    shift
+  done
+  case "$_ts_rest" in
+    *"$_ts_sep")
+      _ts_field="${_ts_rest%"$_ts_sep"}"
+      case "$_ts_field" in *"$_ts_sep"*) ;; *) _ts_rest="$_ts_field" ;; esac
+      ;;
+  esac
+  printf -v "$1" '%s' "$_ts_rest" || return 2
+}

package/deploy/sema-up/lib/usage-flags.txt

@@ -0,0 +1,10 @@
+  --interactive=json     机器可读交互协议(sema cloud deploy 渲染用)
+  --yes                  全默认无人值守(与 -f 组合)
+  -f FILE                site 配置(env 形式;machines.yaml=固定形状 mini-parser)
+  --project=NAME         compose project 名(默认 sema;并行试验用)。也是工作目录 ~/.sema-up/<名> 与自动数据根
+                         <盘>/sema-data/<名> 的一段 ⇒ 只收小写字母 / 数字 / - / _,首字符是字母或数字
+  --data-root=DIR        数据卷 bind 到这条目录(缺省:多盘机自动选大盘 <盘>/sema-data/<project>);首装落定不漂移,
+                         一条数据根只归一个项目(根里的 .sema-up-project 标记,别的项目的根一律拒)
+  --dry-run              只打印将执行计划(不写 .env、不起任何容器)
+  --port=N               服务端口(默认 8090);--pg-port/--minio-port/--minio-console-port 同理(端口旗只收 1–65535 的整数)
+  --gateway=URL --model=ID --model-key=K   模型面(带 agent 的档必需)

package/deploy/sema-up/lib/usage-head.txt

@@ -0,0 +1 @@
+用法: sema-up.sh [选项]

package/deploy/sema-up/lib/usage-tail.txt

@@ -0,0 +1,13 @@
+  --registry=true|false  配置中心网站(默认 true;local-plus 默认 false;只收这两个词)
+  --registry-image=REF   sema-registry 镜像(registry=true 必需,可 -f 配置 SEMA_REGISTRY_IMAGE)
+  --git=MODE             none(默认)|provision(一键自建 Gitea)|connect(接已有 git)
+  --git-url=URL --git-token=T   git=connect 的已有服务(Gitea/GitHub/任意三方 git;自动识别,证书不校验)
+  --pg-url=URL           外接第三方 PG(postgres://user:pass@host:port/db;连不上会先检,不部署本地 PG)
+  --s3-endpoint=URL --s3-access-key=K --s3-secret-key=S   外接第三方 S3(兼容协议即可;不部署本地 MinIO)
+  --git-http-port=N --git-ssh-port=N   自建 Gitea 端口(默认 3300/2222)
+  --gitea-image=REF      自建 Gitea 镜像(默认 gitea/gitea:1.24)
+  --pg-host=H --pg-password=P --minio-endpoint=URL --minio-password=P   local-plus 远端数据面
+  --kube=MODE            full-cluster 单机两态:existing(已有 kubeconfig)|k3s(本机装 k3s)
+  --kubeconfig=PATH      --kube=existing 的 kubeconfig(缺省 $KUBECONFIG 或 ~/.kube/config)
+  --teardown             卸载本 project(数据卷保留;--teardown-volumes 连卷删)
+  --skip-preflight       跳过预检(不建议)

package/deploy/sema-up/preflight.sh

@@ -4,7 +4,7 @@
 # (sema cloud deploy 渲染用,同一交互协议的 infeasible:{reason,suggestion} 字段)。
 # 只读探测,零改动,幂等。退出码:0=可部署(可能有 WARN),1=存在 BLOCK 项。
 set -u
-# >>> 自身目录(五个入口逐字同一段)
+# [[[ 自身目录(五个入口逐字同一段)
 # HERE = 本脚本**真实文件**所在目录。经 npm bin 软链(node_modules/.bin/sema-up)调用时 $0 是软链路径,
 # 按它的目录找 lib/ 会落进 .bin/ ⇒ 逐跳解软链。只用不带参数的 readlink(macOS 自带 bash 3.2 / BSD readlink 没有 -f)。
 # 库要在知道 HERE 之后才找得到,所以这段不能收进库里:五个入口各持同一段,逐字一致由测试判。
@@ -16,11 +16,13 @@ while [ -L "$_self" ]; do
 done
 HERE="$(cd "$(dirname "$_self")" && pwd)"
 unset _self _hops _dir
-# <<< 自身目录
+# ]]] 自身目录
 # 自动数据根的路径形只在 lib/dataroot.sh 定义一次:下面「多盘机」建议句与 sema-up 自动选的根同一条规则。
 . "$HERE/lib/dataroot.sh"
 # 取值旗的形:判据与词表同 sema-up.sh 一处定义。
 . "$HERE/lib/flagshape.sh"
+# 把一段文本按行 / 按词 / 按分隔字符读进变量的三只函数(不用 here-document / here-string)。
+. "$HERE/lib/shell-text.sh"
 log() { printf '[preflight] %s\n' "$*" >&2; }
 
 JSON=false
@@ -111,13 +113,13 @@ else add OK disk "${DISK_GB}G avail /" "" ""; fi
 BEST_MNT="" BEST_GB=0
 if [ "$OS_ID" = "macos" ]; then DF_OUT="$(df -g 2>/dev/null | awk '$1 ~ /^\/dev\// {print $9"\t"$4}')"
 else DF_OUT="$(df -BG --output=source,avail,target 2>/dev/null | awk '$1 ~ /^\/dev\// {gsub(/G/,"",$2); print $3"\t"$2}')"; fi
-while IFS="$(printf '\t')" read -r mnt avail; do
+df_rest="$DF_OUT"$'\n'
+while text_pop_line df_rest df_line; do
+  IFS=$'\t' text_words "$df_line" mnt avail
   [ -z "$mnt" ] && continue
   case "$mnt" in /boot*|/efi*|/System/*|/private/var/vm) continue ;; esac
   if [ "${avail:-0}" -gt "$BEST_GB" ] 2>/dev/null; then BEST_GB="$avail"; BEST_MNT="$mnt"; fi
-done <<EOF_DF
-$DF_OUT
-EOF_DF
+done
 if [ -n "$BEST_MNT" ] && [ "$BEST_MNT" != "/" ] && [ "$BEST_GB" -gt "${DISK_GB:-0}" ]; then
   add WARN disk-alt "$BEST_MNT ${BEST_GB}G avail" "存在比 / 更大的数据盘(多盘机)" "--data-root=$(dataroot_for_disk "$BEST_MNT" "$PROJECT")(sema-up 未显式指定时会自动选它;数据根按项目分)"
 fi
@@ -172,7 +174,7 @@ if $JSON; then
   printf '{"profile":"%s","findings":[' "$PROFILE"
   first=true
   for f in "${FINDINGS[@]}"; do
-    IFS='|' read -r lv ck rs why fix <<<"$f"
+    text_split '|' "$f" lv ck rs why fix
     [ "$lv" = "BLOCK" ] && BLOCKS=$((BLOCKS+1))
     $first || printf ','
     first=false
@@ -183,7 +185,7 @@ if $JSON; then
 else
   printf '── sema-up preflight(profile=%s)──\n' "$PROFILE"
   for f in "${FINDINGS[@]}"; do
-    IFS='|' read -r lv ck rs why fix <<<"$f"
+    text_split '|' "$f" lv ck rs why fix
     [ "$lv" = "BLOCK" ] && BLOCKS=$((BLOCKS+1))
     printf '[%-5s] %-16s %s' "$lv" "$ck" "$rs"
     [ -n "$why" ] && printf ' — %s' "$why"