feat: expose control plane research attention

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

docs/qsl_unified_control_console_architecture_v1.zh-CN.md

@@ -33,6 +33,8 @@
 
 新增两层快照契约：各仓只发布自己的 `qsl_control_plane_source_snapshot.v1`；Worker 汇总为给网页读取的 `qsl_control_plane_dashboard.v1`。它汇总候选身份、当前阶段、数据新鲜度、P1/P2/P3 摘要、机器建议和 P6 是否等待所有者决定；不携带原始行情、账户、完整订单、文件路径或密钥。
 
+`data_status=ready` 只说明来源快照已同步，**不**表示策略已验证、可执行或有订单授权。Worker 另行给出只读 `attention`：任一策略、组合或插件候选处于 `DEFERRED` / `PARKED`、来源产生脱敏错误，或没有候选时为 `attention_required`；缺快照为 `unavailable`；其余为 `research_only`。该字段只帮助监控和界面避免“工作流绿灯即策略绿灯”的误读，绝不提升 P4–P6 权限。
+
 Worker 以**独立于 dispatch token 的同步身份**接收来源快照、按 `source_id` 分开保存在 KV，并只向已登录 allowlist 用户读取聚合结果。这样一个仓库不能覆盖另一个仓库的候选；同名候选会 fail-closed 并记录冲突。快照缺失、过期、未来时间戳或 schema 不符时，页面显示 `unavailable` / `stale`，不伪造全局健康结论。当前日更来源默认 36 小时后变为 stale，适配交易日节奏而不把周末误报为实时故障。
 
 执行状态另用独立的 `qsl_execution_evidence_source_snapshot.v1` 与 `qsl_execution_evidence_dashboard.v1` 投影。每一条记录的身份是“固定策略 revision × 目标平台 × 当前执行通道”，显示策略、目标数据和目标执行证据，以及该平台的 shadow / paper 能力。它有独立 KV 前缀和同步 token，不能覆盖 P1–P3 候选快照，也不能创建订单、资金变更或 P6 授权。没有来源时页面保持空状态；在某个平台已有 live 或 paper 记录，也只是一项该目标的证据，不自动推广到别的平台。

schemas/qsl-control-plane-dashboard.v1.schema.json

@@ -21,6 +21,20 @@
         "owner_decision_required": { "type": "integer", "minimum": 0, "maximum": 1000 }
       }
     },
+    "attention": {
+      "type": "object",
+      "description": "Derived research-state attention. It never grants execution authority.",
+      "additionalProperties": false,
+      "required": ["status", "reason_codes"],
+      "properties": {
+        "status": { "enum": ["research_only", "attention_required", "unavailable"] },
+        "reason_codes": {
+          "type": "array",
+          "maxItems": 20,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,63}$" }
+        }
+      }
+    },
     "candidates": {
       "type": "array",
       "maxItems": 1000,

tests/strategy_switch_worker_validation.mjs

@@ -2000,6 +2000,10 @@ assert.equal(controlRead.status, 200);
 const controlReadPayload = await controlRead.json();
 assert.equal(controlReadPayload.data_status, "ready");
 assert.deepEqual(controlReadPayload.summary, { candidate_count: 1, deferred: 1, parked: 0, owner_decision_required: 0 });
+assert.deepEqual(controlReadPayload.attention, {
+  status: "attention_required",
+  reason_codes: ["control_plane_candidate_deferred", "safe_notice"],
+});
 assert.equal(controlReadPayload.candidates[0].recommendation.reason, "没有可用的机器建议。");
 assert.equal(controlReadPayload.policy.p6_owner_decision_required, true);
 assert.ok(indexHtml.includes('requestJson("/api/control-plane")'));
@@ -2050,6 +2054,7 @@ const sourceControlRead = await worker.fetch(
 const sourceControlPayload = await sourceControlRead.json();
 assert.equal(sourceControlPayload.data_status, "ready");
 assert.deepEqual(sourceControlPayload.summary, { candidate_count: 1, deferred: 0, parked: 0, owner_decision_required: 0 });
+assert.deepEqual(sourceControlPayload.attention, { status: "research_only", reason_codes: [] });
 assert.equal(sourceControlPayload.candidates[0].candidate_id, "tqqq_core_only_p2_v5");
 
 const conflictingSourceSync = await worker.fetch(
@@ -2061,6 +2066,7 @@ const conflictingSourceSync = await worker.fetch(
   controlEnv,
 );
 assert.equal(conflictingSourceSync.status, 200);
+
 const conflictingSourceRead = await worker.fetch(
   new Request("https://switch.example/api/control-plane", { headers: controlCookieHeaders }),
   controlEnv,
@@ -2069,6 +2075,39 @@ const conflictingSourcePayload = await conflictingSourceRead.json();
 assert.equal(conflictingSourcePayload.summary.candidate_count, 0);
 assert.ok(conflictingSourcePayload.errors.includes("control_plane_duplicate_candidate"));
 
+const parkedSourceSync = await worker.fetch(
+  new Request("https://switch.example/api/internal/sync-control-plane-source", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${controlSyncValue}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      ...controlSourcePayload,
+      source_id: "uesp.soxl_daily_research",
+      candidates: [{
+        ...controlSourcePayload.candidates[0],
+        candidate_id: "soxl_soxx_trend_income",
+        lifecycle: { stage: "P3", status: "parked" },
+        evidence: { ...controlSourcePayload.candidates[0].evidence, p3_evidence_id: null },
+        recommendation: { code: "park", reason: "P3 parked: runtime_internal_failure." },
+      }],
+      errors: ["p3_parked"],
+    }),
+  }),
+  controlEnv,
+);
+assert.equal(parkedSourceSync.status, 200);
+const parkedControlRead = await worker.fetch(
+  new Request("https://switch.example/api/control-plane", { headers: controlCookieHeaders }),
+  controlEnv,
+);
+const parkedControlPayload = await parkedControlRead.json();
+assert.equal(parkedControlPayload.data_status, "ready");
+assert.equal(parkedControlPayload.attention.status, "attention_required");
+assert.deepEqual(parkedControlPayload.attention.reason_codes, [
+  "control_plane_candidate_parked",
+  "control_plane_duplicate_candidate",
+  "p3_parked",
+]);
+
 const executionEvidenceSyncValue = ["execution", "evidence", "sync"].join("-");
 const executionEvidenceEnv = { ...controlEnv, EXECUTION_EVIDENCE_SYNC_TOKEN: executionEvidenceSyncValue };
 const executionEvidenceCookie = await __test.makeSession("health-user", [], executionEvidenceEnv);

web/strategy-switch-console/README.zh-CN.md

@@ -172,6 +172,8 @@ GET  /api/control-plane
 
 新接入应调用 source 路径并提交 `qsl_control_plane_source_snapshot.v1`：Worker 按 `source_id` 分开保存，再聚合为 `qsl_control_plane_dashboard.v1`，所以一个仓库不会覆盖另一个仓库的候选。旧的完整快照路径仅为兼容保留。来源写入仍只保存候选生命周期、脱敏证据标识、新鲜度和机器建议；它会重新计算计数、丢弃未定义字段，并拒绝不一致的 P6 状态。读取仍要求登录 allowlist；日更来源超过默认 36 小时 TTL 时返回 `stale`。
 
+聚合快照的 `data_status=ready` 仅代表快照送达。请同时读取只读 `attention`：任何 `DEFERRED` / `PARKED` 的策略、组合或插件候选、上游错误或空候选都会使其成为 `attention_required`；这用于告警与界面提示，绝不是自动调参、自动修复、paper/shadow/live 或下单授权。
+
 这个接口不是订单、paper、shadow 或 live API。`CONTROL_PLANE_SYNC_TOKEN` 必须与 OAuth、workflow dispatch、策略 root 和任何券商凭证完全分离。部署 workflow 会在 `runtime-strategy-switch` environment 提供该 secret 时，把它同步为 Worker secret；每个来源仓库需要保存同一值到其专用 GitHub Environment，URL 使用只读控制台的 `/api/internal/sync-control-plane-source`。
 
 ## 策略 Profile 对齐规范

web/strategy-switch-console/app.js

@@ -823,14 +823,18 @@
         controlParked: "已停车",
         controlOwnerDecision: "等待我决定",
         controlCandidateBoard: "候选生命周期",
-        controlDataReady: "快照已加载",
+        controlDataReady: "快照已同步（不代表策略可运行）",
         controlDataStale: "快照已过期",
         controlDataUnavailable: "等待可用快照",
+        controlAttentionResearchOnly: "仅研究，未授予执行权限",
+        controlAttentionRequired: "研究状态需要关注",
+        controlAttentionUnavailable: "尚无已验证研究状态",
         controlComputedAt: "最近计算：{time}",
         controlLoginNotice: "登录后读取私有全局快照；没有快照时不会展示虚构信息。",
         controlStaleNotice: "全局快照已超过允许的新鲜度窗口；页面保留原始记录，但不把它作为当前结论。",
         controlUnavailableNotice: "还没有可用的全局快照；当前页面保持 fail-closed 空状态。",
         controlUpstreamNotice: "快照已加载，但有 {count} 个上游提示；缺失信息不会被补成推断结论。",
+        controlAttentionNotice: "研究状态需要关注（延期 {deferred}、停车 {parked}、信号 {signals}）。快照送达不等于策略验证或执行授权；系统保持不交易。",
         controlEmptyCandidates: "暂无可展示的候选快照。",
         controlNoRecommendation: "没有可用的机器建议。",
         controlStageMeta: "阶段：{stage} · 状态：{status} · 证据：{freshness}",
@@ -1040,14 +1044,18 @@
         controlParked: "Parked",
         controlOwnerDecision: "Needs my decision",
         controlCandidateBoard: "Candidate lifecycle",
-        controlDataReady: "Snapshot loaded",
+        controlDataReady: "Snapshot synced (not strategy readiness)",
         controlDataStale: "Snapshot is stale",
         controlDataUnavailable: "Waiting for a usable snapshot",
+        controlAttentionResearchOnly: "Research only; no execution authority",
+        controlAttentionRequired: "Research state needs attention",
+        controlAttentionUnavailable: "No verified research state",
         controlComputedAt: "Last computed: {time}",
         controlLoginNotice: "Sign in to read the private global snapshot. Missing data is never invented.",
         controlStaleNotice: "This snapshot is outside its freshness window. The record remains visible, but is not a current conclusion.",
         controlUnavailableNotice: "No usable global snapshot is available yet. This page remains fail-closed and empty.",
         controlUpstreamNotice: "The snapshot loaded with {count} upstream notice(s); missing information is never inferred.",
+        controlAttentionNotice: "Research needs attention ({deferred} deferred, {parked} parked, {signals} signal(s)). Snapshot delivery is not strategy validation or execution authority; the system remains no-order.",
         controlEmptyCandidates: "No candidate snapshot is available to display.",
         controlNoRecommendation: "No machine recommendation is available.",
         controlStageMeta: "Stage: {stage} · status: {status} · evidence: {freshness}",
@@ -1294,6 +1302,7 @@
           data_status: "unavailable",
           computed_at: null,
           summary: { candidate_count: 0, deferred: 0, parked: 0, owner_decision_required: 0 },
+          attention: { status: "unavailable", reason_codes: ["control_plane_source_unavailable"] },
           candidates: [],
           policy: { p4_p5_automation: "not_configured", p6_owner_decision_required: true },
           errors: [],
@@ -3373,6 +3382,14 @@
         data_status: ["ready", "stale", "unavailable"].includes(payload.data_status) ? payload.data_status : "unavailable",
         computed_at: payload.computed_at || null,
         summary: payload.summary && typeof payload.summary === "object" ? payload.summary : {},
+        attention: payload.attention && typeof payload.attention === "object" && !Array.isArray(payload.attention)
+          ? {
+            status: ["research_only", "attention_required", "unavailable"].includes(payload.attention.status)
+              ? payload.attention.status
+              : "unavailable",
+            reason_codes: Array.isArray(payload.attention.reason_codes) ? payload.attention.reason_codes : [],
+          }
+          : { status: "unavailable", reason_codes: ["control_plane_attention_missing"] },
         candidates: candidates.filter((item) => item && typeof item === "object" && item.lifecycle && typeof item.lifecycle === "object"),
         policy: payload.policy && typeof payload.policy === "object" ? payload.policy : {},
         errors: Array.isArray(payload.errors) ? payload.errors : [],
@@ -3385,10 +3402,17 @@
         : (status === "stale" ? t("controlDataStale") : t("controlDataUnavailable"));
     }
 
+    function controlPlaneAttentionText(attention) {
+      const status = attention?.status || "unavailable";
+      if (status === "research_only") return t("controlAttentionResearchOnly");
+      if (status === "attention_required") return t("controlAttentionRequired");
+      return t("controlAttentionUnavailable");
+    }
+
     function renderControlPlane() {
       const payload = state.controlPlane.payload;
       const summary = payload.summary || {};
-      el("control-plane-status").textContent = controlPlaneDataStatusText(payload.data_status);
+      el("control-plane-status").textContent = `${controlPlaneDataStatusText(payload.data_status)} · ${controlPlaneAttentionText(payload.attention)}`;
       el("control-plane-computed-at").textContent = payload.computed_at
         ? t("controlComputedAt").replace("{time}", new Date(payload.computed_at).toLocaleString())
         : t("controlComputedAt").replace("{time}", "—");
@@ -3404,6 +3428,11 @@
         notice.textContent = t("controlStaleNotice");
       } else if (payload.data_status !== "ready") {
         notice.textContent = t("controlUnavailableNotice");
+      } else if (payload.attention?.status === "attention_required") {
+        notice.textContent = t("controlAttentionNotice")
+          .replace("{deferred}", String(Number(summary.deferred) || 0))
+          .replace("{parked}", String(Number(summary.parked) || 0))
+          .replace("{signals}", String(payload.attention.reason_codes?.length || 0));
       } else if (payload.errors?.length) {
         notice.textContent = t("controlUpstreamNotice").replace("{count}", payload.errors.length);
       } else {
@@ -3793,6 +3822,7 @@
           data_status: "unavailable",
           computed_at: null,
           summary: { candidate_count: 0, deferred: 0, parked: 0, owner_decision_required: 0 },
+          attention: { status: "unavailable", reason_codes: ["control_plane_request_failed"] },
           candidates: [],
           policy: { p4_p5_automation: "not_configured", p6_owner_decision_required: true },
           errors: ["control_plane_request_failed"],

web/strategy-switch-console/app_js.js

@@ -42,6 +42,7 @@ const STRATEGY_HEALTH_DATA_STATUSES = ["ready", "unavailable", "stale"];
 const CONTROL_PLANE_SNAPSHOT_KEY = "control_plane_snapshot";
 const CONTROL_PLANE_SOURCE_PREFIX = "control_plane_source:";
 const CONTROL_PLANE_SOURCE_SCHEMA_VERSION = "qsl_control_plane_source_snapshot.v1";
+const CONTROL_PLANE_ATTENTION_STATUSES = ["research_only", "attention_required", "unavailable"];
 const CONTROL_PLANE_MAX_SOURCES = 100;
 const CONTROL_PLANE_MAX_BODY_BYTES = 256 * 1024;
 // The current source is a once-per-trading-day P1/P3 lane, rather than a live
@@ -1663,19 +1664,25 @@ async function aggregateControlPlaneSources(env) {
 
   const dataStatus = hasStaleSource ? "stale" : (hasReadySource ? "ready" : "unavailable");
   const uniqueCandidates = candidates.filter((candidate) => !duplicateCandidateIds.has(candidate.candidate_id));
+  const uniqueErrors = uniqueStrings(errors);
   return {
     schema_version: "qsl_control_plane_dashboard.v1",
     generated_at: earliestControlPlaneTimestamp(timestamps),
     computed_at: earliestControlPlaneTimestamp(timestamps),
     data_status: dataStatus,
     summary: normalizeControlPlaneSummary(uniqueCandidates),
+    attention: normalizeControlPlaneAttention({
+      dataStatus,
+      candidates: uniqueCandidates,
+      errors: uniqueErrors,
+    }),
     candidates: uniqueCandidates,
     policy: normalizeControlPlanePolicy({
       p4_p5_automation: "not_configured",
       p6_owner_decision_required: true,
       notice: "P1–P3 自动研究已接入；P4/P5 尚未配置，live 仍需所有者明确决定。",
     }, "aggregated control plane policy"),
-    errors: uniqueStrings(errors),
+    errors: uniqueErrors,
   };
 }
 
@@ -2233,15 +2240,17 @@ function normalizeControlPlaneSnapshot(payload, fieldName = "control plane snaps
   }
   const dataStatus = cleanChoice(payload.data_status || "unavailable", STRATEGY_HEALTH_DATA_STATUSES, `${fieldName}.data_status`);
   const candidates = dataStatus === "unavailable" ? [] : normalizeControlPlaneCandidates(payload.candidates, fieldName);
+  const errors = normalizeStrategyHealthErrors(payload.errors);
   return {
     schema_version: "qsl_control_plane_dashboard.v1",
     generated_at: normalizeStrategyHealthTimestamp(payload.generated_at, `${fieldName}.generated_at`, true),
     computed_at: normalizeStrategyHealthTimestamp(payload.computed_at, `${fieldName}.computed_at`, true),
     data_status: dataStatus,
     summary: normalizeControlPlaneSummary(candidates),
+    attention: normalizeControlPlaneAttention({ dataStatus, candidates, errors }),
     candidates,
     policy: normalizeControlPlanePolicy(payload.policy, fieldName),
-    errors: normalizeStrategyHealthErrors(payload.errors),
+    errors,
   };
 }
 
@@ -2354,6 +2363,27 @@ function normalizeControlPlaneSummary(candidates) {
   };
 }
 
+function normalizeControlPlaneAttention({ dataStatus, candidates, errors }) {
+  const normalizedCandidates = Array.isArray(candidates) ? candidates : [];
+  const normalizedErrors = uniqueStrings(Array.isArray(errors) ? errors : []);
+  const reasonCodes = new Set(normalizedErrors);
+  if (dataStatus !== "ready") reasonCodes.add("control_plane_source_unavailable");
+  if (!normalizedCandidates.length && dataStatus === "ready") reasonCodes.add("control_plane_candidate_missing");
+  if (normalizedCandidates.some((item) => item.lifecycle?.status === "deferred")) {
+    reasonCodes.add("control_plane_candidate_deferred");
+  }
+  if (normalizedCandidates.some((item) => item.lifecycle?.status === "parked")) {
+    reasonCodes.add("control_plane_candidate_parked");
+  }
+  const status = dataStatus !== "ready"
+    ? "unavailable"
+    : (reasonCodes.size ? "attention_required" : "research_only");
+  return {
+    status: cleanChoice(status, CONTROL_PLANE_ATTENTION_STATUSES, "control plane attention status"),
+    reason_codes: [...reasonCodes].sort(),
+  };
+}
+
 function normalizeControlPlanePolicy(value, fieldName) {
   const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   if (source.p6_owner_decision_required !== true) {
@@ -2514,6 +2544,7 @@ function emptyControlPlanePayload(errorCode) {
     computed_at: null,
     data_status: "unavailable",
     summary: { candidate_count: 0, deferred: 0, parked: 0, owner_decision_required: 0 },
+    attention: { status: "unavailable", reason_codes: ["control_plane_source_unavailable", errorCode] },
     candidates: [],
     policy: { p4_p5_automation: "not_configured", p6_owner_decision_required: true, notice: "live 仍需所有者明确决定。" },
     errors: [errorCode],