pikasTech-unidesk/.agents/skills/unidesk-temporal/SKILL.md

name, description

name	description
unidesk-temporal	UniDesk Temporal 基础设施与工作流运维技能，覆盖 YAML-first 受控部署、native PostgreSQL、Kubernetes/逻辑 namespace、共享 gRPC、Web 管理入口、统一管理员密码、状态验证，以及 native SDK worker/workflow smoke。用户提到 Temporal、workflow、activity、worker、task queue、temporal.hwpod.com、Temporal namespace、Temporal Web 或 Temporal smoke 时使用。

UniDesk Temporal

核心事实

• 配置真相位于 config/platform-infra/temporal.yaml。
• 数据库真相位于 config/platform-db/postgres-nc01.yaml：
  • 使用 NC01 host native PostgreSQL；
  • 禁止在 Kubernetes 内创建 PostgreSQL workload 或 PVC。
• Kubernetes namespace 固定为 temporal。
• 默认业务逻辑 namespace 固定为 unidesk，保留期由 owning YAML 声明。
• 集群内共享入口为 temporal-frontend.temporal.svc.cluster.local:7233。
• Web 管理入口为 https://temporal.hwpod.com。
• Web 用户名来自 owning YAML；密码只来自 /root/.unidesk/.env/unified-admin-password.txt，并通过 unidesk-secret 分发。

操作边界

• 基础设施变更必须加载 $unidesk-ymalops，只修改 owning YAML 和受控 CLI 渲染器。
• 部署、状态和验证只使用 bun scripts/cli.ts platform-infra temporal ...。
• 临时 smoke worker 可以在 NC01 host native 启动，并跳过 CI/CD；不得把临时 worker 固化为 Kubernetes workload。
• 正式应用 worker 的交付仍遵循应用自身的 YAML/Git/CI/CD 流程。
• 不得硬编码 Service ClusterIP；native client 每次从 Service 只读解析当前 ClusterIP。
• 不得读取、打印或从 Kubernetes Secret、Pod env、数据库和日志反解密码。
• 不得用原生 kubectl apply/delete、Helm 或 Compose 建立第二套 Temporal 部署入口。

部署顺序

1. 检查 native PostgreSQL 计划并受控收敛：

bun scripts/cli.ts platform-db postgres plan \
  --config config/platform-db/postgres-nc01.yaml
bun scripts/cli.ts platform-db postgres apply \
  --config config/platform-db/postgres-nc01.yaml \
  --confirm

2. 通过统一 Secret 配置同步 Web 管理密码：

bun scripts/cli.ts secrets plan \
  --config config/secrets-distribution.yaml \
  --scope temporal \
  --target temporal-nc01
bun scripts/cli.ts secrets sync \
  --config config/secrets-distribution.yaml \
  --scope temporal \
  --target temporal-nc01 \
  --confirm

3. 先 plan 和服务端 dry-run，再执行异步 apply：

bun scripts/cli.ts platform-infra temporal plan --target NC01
bun scripts/cli.ts platform-infra temporal apply --target NC01 --dry-run
bun scripts/cli.ts platform-infra temporal apply --target NC01 --confirm

4. 按 apply 返回的 job ID 查询终态，再验证运行面：

bun scripts/cli.ts job status <job-id> --tail-bytes 12000
bun scripts/cli.ts platform-infra temporal status --target NC01 --full
bun scripts/cli.ts platform-infra temporal validate --target NC01

5. 只在 Temporal ready 后收敛共享公网入口：

bun scripts/cli.ts platform-infra public-edge apply --target NC01 --confirm
bun scripts/cli.ts platform-infra public-edge status --target NC01

验收标准

• Temporal server 与 UI 的 readyReplicas 达到 YAML 声明值。
• frontend/UI endpoint 均存在。
• 数据库模式显示 nc01-host-native-postgresql，Secret 只披露 presence/fingerprint，且 valuesPrinted=false。
• 逻辑 namespace unidesk 存在。
• https://temporal.hwpod.com/healthz 返回 200。
• 未认证访问 Web 根路径返回 401。
• 管理页面使用 repo-owned typed web-probe 命令验收：

bun scripts/cli.ts web-probe product-smoke \
  --product temporal \
  --target NC01 \
  --profile admin-readonly

• 命令从 Temporal owning YAML 解析公网入口、runner、Basic Auth 合同、SecretRef、视口和证据上限：
  • 禁止传入 URL、用户名或密码覆盖；
  • 只输出 Secret presence/fingerprint、DOM/网络/控制台有界摘要和工件哈希；
  • 必须保持 mutation=false、valuesPrinted=false。
• public-edge status 可能被其他站点的探针拉低；必须同时核对 Temporal 单站点证据，不能把无关站点故障归因给 Temporal。

Native Workflow Smoke

• 使用 $unidesk-trans 的远程临时实验合同：
  • route 使用 NC01；
  • work_dir 使用唯一 /tmp/<task-id>；
  • worker、client、task queue 和 workflow ID 均为一次性；
  • 使用官方 Temporal SDK；
  • 输出只保留 namespace、task queue、workflow ID、预期结果和 worker stop 状态；
  • 成功或失败后幂等清理整个实验目录。
• 先动态解析 native 连接地址：

trans NC01:k3s kubectl -n temporal get service temporal-frontend \
  -o jsonpath={.spec.clusterIP}:{.spec.ports[0].port}

• smoke 必须完成以下闭环：
  • native worker 连接当前 Service ClusterIP；
  • client 在 unidesk namespace 提交唯一 workflow；
  • workflow 调用至少一个 activity；
  • client 校验精确返回值；
  • worker 明确进入 STOPPED；
  • 删除临时依赖、脚本、日志和 PID 文件。
• NC01 /tmp 是独立 tmpfs；遇到 ENOSPC 时加载 $unidesk-gc，先区分根盘与 /tmp，不得直接清理 k3s、containerd、PVC 或并行任务目录。

常见故障

• server 报 dynamic config 文件不存在：
  • 检查 YAML 的 runtime.server.dynamicConfigFilePath；
  • 路径必须指向当前 server 镜像内实际文件。
• UI 把 TEMPORAL_UI_PORT=tcp://... 当整数解析：
  • 检查 server/UI Pod spec 的 enableServiceLinks: false；
  • 不在容器内覆盖 Kubernetes 自动环境变量。
• /healthz 返回 401：
  • Caddy sidecar 必须用互斥 handle /healthz 与认证 handle；
  • 其他路径继续启用 Basic Auth。
• native host 无法解析 .svc.cluster.local：
  • 只读解析当前 Service ClusterIP；
  • 不修改 /etc/hosts，不增加 NodePort 或公网 gRPC。

跟踪与配合

• 基础设施可靠性任务记录在 docs/MDTODO/platform-infra-runtime-reliability.md。
• 详细方案、偏差与验收证据写入对应 GitHub issue，并使用 $unidesk-gh 受控入口。
• 跨 host 调试与临时 native smoke 使用 $unidesk-daddev 和 $unidesk-trans。
• Web 公网验收使用 $unidesk-webdev。
• 统一管理员密码生命周期使用 $unidesk-secret。