From bfb0ed1acdca32170859a72c14dba2b498427245 Mon Sep 17 00:00:00 2001
From: Codex <codex@local>
Date: Thu, 16 Jul 2026 19:36:32 +0200
Subject: [PATCH] =?UTF-8?q?feat(skill):=20=E5=A2=9E=E5=8A=A0=20UniDesk=20T?=
 =?UTF-8?q?emporal=20=E8=BF=90=E7=BB=B4=E8=83=BD=E5=8A=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .agents/skills/unidesk-temporal/SKILL.md      | 136 ++++++++++++++++++
 .../unidesk-temporal/agents/openai.yaml       |   4 +
 2 files changed, 140 insertions(+)
 create mode 100644 .agents/skills/unidesk-temporal/SKILL.md
 create mode 100644 .agents/skills/unidesk-temporal/agents/openai.yaml

diff --git a/.agents/skills/unidesk-temporal/SKILL.md b/.agents/skills/unidesk-temporal/SKILL.md
new file mode 100644
index 00000000..6af0f391
--- /dev/null
+++ b/.agents/skills/unidesk-temporal/SKILL.md
@@ -0,0 +1,136 @@
+---
+name: unidesk-temporal
+description: 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 计划并受控收敛：
+
+```bash
+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 管理密码：
+
+```bash
+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：
+
+```bash
+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 查询终态，再验证运行面：
+
+```bash
+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 后收敛共享公网入口：
+
+```bash
+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` 命令；缺少 Temporal typed login smoke 时记录工具缺口，不得临时读取统一密码或复制一次性浏览器脚本。
+- `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 连接地址：
+
+```bash
+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`。
diff --git a/.agents/skills/unidesk-temporal/agents/openai.yaml b/.agents/skills/unidesk-temporal/agents/openai.yaml
new file mode 100644
index 00000000..5fa0c046
--- /dev/null
+++ b/.agents/skills/unidesk-temporal/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "UniDesk Temporal"
+  short_description: "受控管理 UniDesk Temporal 基础设施、工作流与 smoke 验证"
+  default_prompt: "使用 $unidesk-temporal 检查 Temporal 运行面并执行一次受控 workflow smoke。"