feat: add PikaOA YAML-first test runtime

AGENTS.md

@@ -145,5 +145,6 @@
 - OTel/可观测性: `docs/reference/observability.md`。
 - YAML-first: `docs/reference/yaml-first-ops.md`。
 - Platform infrastructure: `docs/reference/platform-infra.md`。
+- PikaOA 临时测试运行面: `docs/reference/pikaoa.md`。
 - Webterm 配置与受控部署: `docs/reference/webterm.md`。
 - Secretary: `docs/reference/secretary-reference.md`。

config/fixtures/pikaoa-test-target.yaml

@@ -0,0 +1,88 @@
+version: 1
+kind: pikaoa-platform-delivery
+
+metadata:
+  id: pikaoa-enterprise-fixture
+  owner: unidesk
+  repository: pikainc/pikaoa
+  spec: PJ2026-03
+
+testRuntime:
+  defaultTargetId: TEST01
+  targets:
+    TEST01:
+      enabled: true
+      validationOnly: true
+      dedicated: true
+      node: TEST01
+      route: TEST01:k3s
+      namespacePrefix: pikaoa-test
+      ttlSeconds: 7200
+      waitTimeoutSeconds: 180
+      fieldManager: unidesk-pikaoa-test-target
+      cleanup:
+        mode: delete-namespace
+        requireOwnershipLabels: true
+      source:
+        mode: prebuilt-images
+        repository: pikainc/pikaoa
+        commitPolicy: cli-required
+        images:
+          api: registry.invalid/pikaoa/api:${commit}
+          worker: registry.invalid/pikaoa/worker:${commit}
+        pullPolicy: IfNotPresent
+      database:
+        image: postgres:16-alpine
+        name: pikaoa_test
+        username: pikaoa_test
+        port: 5432
+        password:
+          sourceRef: ./secrets/pikaoa-test-database-password.txt
+          targetKey: PIKAOA_DATABASE_PASSWORD
+      runtime:
+        secretName: pikaoa-test-runtime
+        apiPort: 8080
+        workerMetricsPort: 8081
+        workerInterval: 2s
+        outbox:
+          batchSize: 50
+          maxAttempts: 4
+          retryDelay: 2s
+        sessionTTL: 8h
+        shutdownTimeout: 10s
+        administrator:
+          username: admin
+          password:
+            sourceRef: ./secrets/pikaoa-test-admin-password.txt
+            targetKey: PIKAOA_BOOTSTRAP_ADMIN_PASSWORD
+        employee:
+          username: employee
+          password:
+            sourceRef: ./secrets/pikaoa-test-employee-password.txt
+            targetKey: PIKAOA_BOOTSTRAP_EMPLOYEE_PASSWORD
+        sessionSecret:
+          sourceRef: ./secrets/pikaoa-test-session-secret.txt
+          targetKey: PIKAOA_SESSION_SECRET
+      observability:
+        otlpEndpoint: http://otel-collector.observability.svc.cluster.local:4318
+        prometheus:
+          scrape: true
+          apiPath: /metrics
+          workerPath: /metrics
+        exporterFailure:
+          warning: true
+          blocking: false
+      probes:
+        api:
+          livenessPath: /healthz
+          readinessPath: /readyz
+        worker:
+          livenessPath: /healthz
+          readinessPath: /readyz
+
+delivery:
+  targets:
+    PROD:
+      namespace: pikaoa
+      ci:
+        namespace: pikaoa-ci

config/pikaoa.yaml

@@ -26,6 +26,11 @@ modules:
     events: transactional-outbox
     workers: named-consumer
 
+testRuntime:
+  # 专用测试集群 target 由用户明确声明后才能启用；空对象表示当前不允许远端测试运行。
+  defaultTargetId: null
+  targets: {}
+
 delivery:
   targets:
     NC01:

docs/reference/pikaoa.md

@@ -0,0 +1,72 @@
+# PikaOA 开发与测试运行面
+
+## 配置真相
+
+- PikaOA 平台配置唯一真相是 `config/pikaoa.yaml`。
+- 正式交付与临时测试运行面职责分离：
+  - `delivery.targets` 只描述正式 CI/CD、GitOps、运行 namespace、数据库和公网暴露；
+  - `testRuntime.targets` 只描述专用测试集群上的临时后端运行面。
+- 禁止把现有节点推断成 PikaOA 专用测试集群。
+- `testRuntime.targets` 为空时表示当前没有获准的测试运行面：
+  - `plan` 和 `status` 返回 `configured=false`、`mutation=false`；
+  - `start` 和 `stop` 在任何远端调用前失败。
+
+## 受控入口
+
+```bash
+bun scripts/cli.ts pikaoa test-target plan
+bun scripts/cli.ts pikaoa test-target status
+bun scripts/cli.ts pikaoa test-target start --target <id> --instance <run-id> --commit <sha> --confirm
+bun scripts/cli.ts pikaoa test-target stop --target <id> --instance <run-id> --confirm
+```
+
+- `plan` 是本地只读渲染入口，不接受 `--dry-run`。
+- `start` 和 `stop` 只在显式 `--confirm` 后执行。
+- `--config <path>` 可用于 fixture 或本地 override；`validationOnly=true` 的 target 永远不连接 route。
+- 默认输出是紧凑文本；`--output json` 或 `--json` 输出单一 JSON 文档。
+
+## 临时运行面
+
+- namespace 固定由 YAML `namespacePrefix` 和 CLI `--instance` 组成。
+- namespace、API、Worker、临时 PostgreSQL、Service 和 Secret 都带以下可审计标签：
+  - `app.kubernetes.io/managed-by=unidesk-pikaoa-test-target`；
+  - `pikaoa.unidesk.io/test-runtime=true`；
+  - `pikaoa.unidesk.io/target=<target-id>`；
+  - `pikaoa.unidesk.io/instance=<run-id>`。
+- `stop` 删除前重新校验 target、instance 和 managed-by 标签，只删除精确实例 namespace。
+- 正式 namespace 保护集合来自以下 YAML 字段：
+  - `delivery.targets.*.namespace`；
+  - `delivery.targets.*.ci.namespace`。
+- 测试入口不得渲染或删除保护集合中的任何对象。
+- PostgreSQL 使用 namespace 内的临时存储，namespace 删除后测试数据随之清理。
+- TTL 和清理策略来自 target YAML：
+  - TTL 写入 namespace annotation；
+  - 当前 `cleanup.mode=delete-namespace`，由显式 `stop` 执行；
+  - `cleanup.requireOwnershipLabels=true` 时，删除前必须校验归属标签；
+  - 不建立额外控制器或长期状态库。
+
+## Secret 与可观测性
+
+- Secret 值只从 YAML `sourceRef` 读取并写入目标 Secret。
+- CLI 输出只显示 `sourceRef`、`targetKey`、presence 和 fingerprint，始终保持 `valuesPrinted=false`。
+- Secret 缺失会在连接测试集群前阻塞 `start`。
+- API 和 Worker 从同一 Secret 挂载严格的 PikaOA runtime YAML。
+- OTel endpoint、Prometheus scrape、指标路径和探针全部由 target YAML 声明。
+- 配置一致性、镜像/commit 漂移和 OTel exporter 失败只产生 `blocking=false` warning，不作为 MVP 门禁。
+
+## 本地验收
+
+`config/fixtures/pikaoa-test-target.yaml` 只用于本地验证：
+
+- 证明 namespace、选择器、工作负载和 Secret 引用的渲染结果；
+- 证明 TTL、OTel、Prometheus 和正式 namespace 保护；
+- fixture target 固定为 `validationOnly=true`，不得用于真实集群操作。
+
+```bash
+bun scripts/cli.ts pikaoa test-target plan \
+  --config config/fixtures/pikaoa-test-target.yaml \
+  --target TEST01 \
+  --instance issue-2046 \
+  --commit 0123456789abcdef \
+  --output json
+```

scripts/cli.ts

@@ -428,6 +428,16 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (top === "pikaoa") {
+    const { runPikaoaCommand } = await import("./src/pikaoa-test-target");
+    const result = await runPikaoaCommand(readConfig(), args.slice(1));
+    if (isRenderedCliResult(result)) {
+      emitText(result.renderedText, result.command || commandName);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+  }
+
   if (top === "platform-db") {
     const result = await runPlatformDbCommand(readConfig(), args.slice(1));
     const ok = (result as { ok?: unknown }).ok !== false;

scripts/src/help.ts

@@ -75,6 +75,7 @@ export function rootHelp(): unknown {
       { command: "hwlab nodes control-plane|git-mirror|hwpod-preinstall|secret|test-accounts --node NC01 --lane v03", description: "Operate the NC01 HWLAB v0.3 development and deployment lane from YAML source truth." },
       { command: "agentrun get|describe|events|logs|result|ack|cancel|dispatch|create|apply|send|control-plane|git-mirror", description: "Use AgentRun v0.1 resource primitives with low-noise human output by default; session follow-up uses send only and the server decides internal steer vs turn." },
       { command: "platform-infra sub2api|langbot|n8n|webterm|wechat-archive ...", description: "Deploy platform-infra services such as Sub2API, LangBot, n8n and Web Terminal, manage YAML-controlled public Caddy/FRP exposure and WeChat archive workflows, and inspect status/logs without printing secrets." },
+      { command: "pikaoa test-target plan|status|start|stop", description: "管理 YAML-first 专用测试集群中的 PikaOA 临时后端运行面；不经过 CI/CD，也不触碰正式 namespace。" },
       { command: "secrets plan|sync|status", description: "Plan, push and inspect YAML-declared local secret source keys to Kubernetes Secrets without printing or reverse-engineering values." },
       { command: "platform-db postgres plan|status|export-secrets|apply", description: "Manage YAML-declared host-native PostgreSQL 16 on PK01 for Sub2API/platform state, with PostgreSQL native TLS and redacted secret exports." },
       { command: "hwlab cd audit --env dev | hwlab cd status --env dev | hwlab cd apply --env dev --dry-run", description: "Archived HWLAB DEV CD diagnostics only; current HWLAB rollout uses NC01 GitOps." },
@@ -1048,6 +1049,7 @@ export async function staticNamespaceHelp(args: string[]): Promise<unknown | nul
     );
   }
   if (top === "platform-infra") return loadHelp(async () => (await import("./platform-infra")).platformInfraHelp(), platformInfraHelpSummary());
+  if (top === "pikaoa") return loadHelp(async () => (await import("./pikaoa-test-target")).pikaoaTestTargetHelp(), { command: "pikaoa test-target", source: "config/pikaoa.yaml#testRuntime" });
   if (top === "platform-db") return platformDbHelp();
   if (top === "secrets") return secretsHelp();
   if (top === "web-probe") return loadHelp(async () => (await import("./web-probe")).webProbeHelp(), webProbeHelpSummary());