): string {
+ return renderToStaticMarkup(createElement(BackthinkUrgencyTags, { item: item(over) }));
+}
+
+// ── ① 穿透行:安静时段内被放行 ⇒ 同时出「穿透安静时段」与档位下限「≥ 高」 ──────
+const bypassed = htmlFor({ urgency: "warning", quietHoursBypassed: true, shouldNotify: true, pushed: true });
+ok(has(bypassed, QUIET_HOURS_BYPASS_LABEL), "穿透的行必须画出「穿透安静时段」");
+ok(has(bypassed, "紧急(≥ 高)"), "档位下限必须显示为「≥ 高」,不能假装是精确档位");
+ok(!has(bypassed, URGENCY_UNKNOWN_LABEL), "有档位的行不得同时显示「档位未知」");
+
+// ── ② 安静时段内被扣下 ⇒ 例常,且**不得**画成穿透 ──────────────────────────
+const held = htmlFor({ urgency: "routine", shouldNotify: false });
+ok(has(held, "例常"), "被扣下的轮次显示「例常」");
+ok(!has(held, QUIET_HOURS_BYPASS_LABEL), "被扣下的轮次绝不能显示穿透");
+
+// ── ③ 键缺席(窗口外的轮次 / 实时帧)⇒ 显示「档位未知」,不是「例常」 ────────
+const unknown = htmlFor({ shouldNotify: true, pushed: true });
+ok(has(unknown, `>${URGENCY_UNKNOWN_LABEL}<`), "没有档位时标签正是「档位未知」");
+ok(!has(unknown, ">例常<"), "标签绝不能是「例常」——那就是把猜当事实");
+ok(!has(unknown, QUIET_HOURS_BYPASS_LABEL), "没有穿透标记时不画穿透");
+
+// ── ④ 后端加了本面板不认识的档位 ⇒ 原样显示,不猜更好听的词 ─────────────────
+const exotic = urgencyTag({ urgency: "emergency" });
+ok(exotic.label === "emergency", "未知档位原样显示");
+ok(!has(htmlFor({ urgency: "emergency" }), ">例常<"), "未知档位不得被解释成「例常」");
+
+// ── ⑤ 安全域档位有独立标签与色调 ────────────────────────────────────────────
+ok(has(htmlFor({ urgency: "critical", quietHoursBypassed: true }), "紧急·安全域"), "critical 显示安全域标签");
+ok(urgencyTag({ urgency: "critical" }).tone === "err", "critical 用 err 色调");
+ok(urgencyTag({ urgency: "warning" }).tone === "warn", "warning(下限)用 warn 色调");
+ok(urgencyTag({ urgency: "routine" }).tone === "neutral", "routine 用中性色调");
+ok(urgencyTag({}).label === URGENCY_UNKNOWN_LABEL, "缺档位时标签是未知");
+ok(quietHoursBypassTag({ quietHoursBypassed: false }) === null, "显式 false 不画穿透(后端只发 true,双向都不画)");
+ok(quietHoursBypassTag({}) === null, "键缺席不画穿透");
+
+// ── ⑥ 两个标记同源可追:提示文字解释「为什么是这个档位」 ─────────────────────
+ok(has(bypassed, "title="), "标记带悬停说明(title),让人能追到判据");
+ok(has(urgencyTag({ urgency: "warning" }).hint, "至少 high") || has(urgencyTag({ urgency: "warning" }).hint, "high"), "档位下限的说明必须点明它只是下限");
+
+// eslint-disable-next-line no-console
+console.log(`BackthinkUrgencyTags.render: ${checks} checks passed`);
diff --git a/frontend/web/src/admin/modules/BackthinkUrgencyTags.tsx b/frontend/web/src/admin/modules/BackthinkUrgencyTags.tsx
new file mode 100644
index 0000000..252667f
--- /dev/null
+++ b/frontend/web/src/admin/modules/BackthinkUrgencyTags.tsx
@@ -0,0 +1,27 @@
+import type { BackthinkItem } from "../../lib/types";
+import { Tag } from "../../components/primitives";
+import { quietHoursBypassTag, urgencyTag } from "./backthinkUrgency";
+
+/** 后台思考行的「穿透安静时段 + 紧急度」标记(Miuix Tag)。
+ *
+ * 为什么单独抽成组件:它是**画出来才算数**的一条(后端字段对了、面板没显示等于没
+ * 做),因此需要一个真实渲染的测试盯着它 —— 见 BackthinkUrgencyTags.render.test.ts。
+ *
+ * ⚠️ 实时帧(bus 上原始 `backthink.Record`)目前不带档位 ⇒ 本次会话新到的行显示
+ * 「档位未知」,重开页面后由历史拉取(`GET /admin/backthink`)补上真值。 */
+export function BackthinkUrgencyTags({ item }: { item: BackthinkItem }): React.ReactNode {
+ const urgency = urgencyTag(item);
+ const bypass = quietHoursBypassTag(item);
+ return (
+ <>
+ {bypass ? (
+
+ {bypass.label}
+
+ ) : null}
+
+ {urgency.label}
+
+ >
+ );
+}
diff --git a/frontend/web/src/admin/modules/ConfigFactsCards.render.test.ts b/frontend/web/src/admin/modules/ConfigFactsCards.render.test.ts
new file mode 100644
index 0000000..9be2f06
--- /dev/null
+++ b/frontend/web/src/admin/modules/ConfigFactsCards.render.test.ts
@@ -0,0 +1,115 @@
+// 配置只读事实卡的**真实渲染**测试。
+//
+// 为什么需要它:这次的产品缺口是「面板看不见运行实例实际在用什么值」,而修好之后的
+// 关键断言是**文案**——安静时段必须按新语义写「只服务『定时主动思考 → 主动搭话』,
+// 不静默回复」,绝不能写成已废弃的「夜间全静默」。文案对不对只有画出来才算数。
+//
+// 跑法(与 channels/accountRow.render.test.ts 同):
+//
+// cd frontend/web \
+// && ./node_modules/.bin/esbuild src/admin/modules/ConfigFactsCards.render.test.ts \
+// --bundle --platform=node --format=cjs \
+// --outfile=/tmp/cyrene-config-facts.render.test.cjs \
+// && node /tmp/cyrene-config-facts.render.test.cjs
+//
+// `tsc --noEmit` 会对本文件做类型检查,因此它只从项目内导入、不 import node:*。
+
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { AdminConfigFacts } from "../../lib/types";
+import { MemoryTidyFactsBody, QuietHoursFactsBody } from "./ConfigFactsCards";
+
+let checks = 0;
+
+function ok(cond: boolean, what: string): void {
+ checks += 1;
+ if (!cond) throw new Error(`FAILED: ${what}`);
+}
+
+function has(haystack: string, needle: string): boolean {
+ return haystack.includes(needle);
+}
+
+const FACTS: AdminConfigFacts = {
+ facts: [
+ { key: "MEMORY_TIDY_ENABLED", value: "true", default: "true", isDefault: true },
+ { key: "MEMORY_TIDY_INTERVAL_SEC", value: "3600", default: "86400", isDefault: false },
+ { key: "MEMORY_TIDY_QUIET_START_HOUR", value: "23", default: "23", isDefault: true },
+ { key: "MEMORY_TIDY_QUIET_END_HOUR", value: "7", default: "7", isDefault: true },
+ { key: "MEMORY_TIDY_RECALL_THRESHOLD", value: "0.8", default: "0.8", isDefault: true },
+ { key: "MEMORY_TIDY_SCAN_LIMIT", value: "5000", default: "5000", isDefault: true },
+ { key: "MEMORY_TIDY_CANDIDATE_LIMIT", value: "20", default: "20", isDefault: true },
+ { key: "QUIET_START_HOUR", value: "1", default: "23", isDefault: false },
+ { key: "QUIET_END_HOUR", value: "5", default: "7", isDefault: false },
+ ],
+ quietHours: { startHour: 1, endHour: 5, disabled: false, label: "01:00-05:00" },
+};
+
+// ── 记忆整理卡:7 个真键名 + 生效值 + 默认/已改 ──────────────────────────────
+const tidyHtml = renderToStaticMarkup(createElement(MemoryTidyFactsBody, { facts: FACTS }));
+for (const key of [
+ "MEMORY_TIDY_ENABLED",
+ "MEMORY_TIDY_INTERVAL_SEC",
+ "MEMORY_TIDY_QUIET_START_HOUR",
+ "MEMORY_TIDY_QUIET_END_HOUR",
+ "MEMORY_TIDY_RECALL_THRESHOLD",
+ "MEMORY_TIDY_SCAN_LIMIT",
+ "MEMORY_TIDY_CANDIDATE_LIMIT",
+]) {
+ ok(has(tidyHtml, key), `记忆整理卡必须列出真键名 ${key}(用户照着它改 .env)`);
+}
+ok(has(tidyHtml, "86400") === false && has(tidyHtml, "3600 秒"), "显示的是**生效值** 3600 秒");
+ok(has(tidyHtml, "已改"), "改过的键必须标「已改」");
+ok((tidyHtml.match(/默认/g) ?? []).length >= 6, "未改的键标「默认」");
+ok(has(tidyHtml, "只产建议"), "必须说清整理只产建议、不自动改记忆");
+ok(has(tidyHtml, "两端都为 0 = 未填"), "必须说清低峰窗口的 0/0 = 未填(否则用户会以为 0/0 是关窗口)");
+
+// ── 安静时段卡:新语义文案(不得出现「夜间全静默」) ────────────────────────
+const quietHtml = renderToStaticMarkup(createElement(QuietHoursFactsBody, { facts: FACTS }));
+ok(has(quietHtml, "01:00-05:00"), "窗口摘要用后端给的口径");
+ok(has(quietHtml, "窗口生效"), "窗口生效态如实标注");
+ok(has(quietHtml, "安静时段只服务"), "必须点明它服务的对象");
+ok(has(quietHtml, "定时主动思考"), "必须点明「定时主动思考 → 主动搭话」");
+ok(has(quietHtml, "不会因为到了安静时段就被静默"), "必须说清回复侧不被静默(新语义)");
+ok(!has(quietHtml, "夜间全静默"), "绝不得写成「夜间全静默」(已废弃的旧实现语义)");
+ok(has(quietHtml, "QUIET_START_HOUR") && has(quietHtml, "QUIET_END_HOUR"), "列出真键名");
+ok(has(quietHtml, "1 时") && has(quietHtml, "5 时"), "显示进程生效的钟点");
+ok(has(quietHtml, "已改"), "被改过的窗口钟点标「已改」");
+
+// ── 关闭态的窗口:必须说「从不生效」,不能画成假窗口 ────────────────────────
+const disabledHtml = renderToStaticMarkup(
+ createElement(QuietHoursFactsBody, {
+ facts: { ...FACTS, quietHours: { startHour: 23, endHour: 23, disabled: true, label: "已关闭" } },
+ }),
+);
+ok(has(disabledHtml, "窗口关闭"), "关闭态必须显示「窗口关闭」");
+ok(has(disabledHtml, "从不生效"), "关闭态的摘要必须说「从不生效」");
+
+// ── 两端写 0(未填 ⇒ 运行时回落):必须在面板上说明,不能显示成「已关闭」 ────
+const fallbackHtml = renderToStaticMarkup(
+ createElement(QuietHoursFactsBody, {
+ facts: {
+ ...FACTS,
+ quietHours: { startHour: 23, endHour: 7, disabled: false, label: "23:00-07:00", fallbackToDefault: true },
+ },
+ }),
+);
+ok(has(fallbackHtml, "运行时回落到默认窗口"), "0/0 的回落必须在面板上说明");
+ok(has(fallbackHtml, "窗口生效"), "回落之后窗口仍然生效,不得画成「窗口关闭」");
+ok(!has(fallbackHtml, "从不生效"), "回落不得被显示成「从不生效」");
+
+// ── 缺事实:渲染「未报告」,不渲染 0 / 默认 ────────────────────────────────
+const partialHtml = renderToStaticMarkup(
+ createElement(MemoryTidyFactsBody, {
+ facts: { ...FACTS, facts: FACTS.facts.filter((f) => f.key !== "MEMORY_TIDY_SCAN_LIMIT") },
+ }),
+);
+ok(has(partialHtml, "未报告"), "后端没给的键必须渲染「未报告」");
+ok(has(partialHtml, "MEMORY_TIDY_SCAN_LIMIT"), "缺的键仍然列出键名(让人知道少了什么)");
+
+// ── 没有数据时不渲染任何编造的默认行 ────────────────────────────────────────
+const emptyHtml = renderToStaticMarkup(createElement(QuietHoursFactsBody, { facts: null }));
+ok(emptyHtml === "", "没有数据时不渲染任何事实行(卡片壳负责 loading/error)");
+
+// eslint-disable-next-line no-console
+console.log(`ConfigFactsCards.render: ${checks} checks passed`);
diff --git a/frontend/web/src/admin/modules/ConfigFactsCards.tsx b/frontend/web/src/admin/modules/ConfigFactsCards.tsx
new file mode 100644
index 0000000..7223854
--- /dev/null
+++ b/frontend/web/src/admin/modules/ConfigFactsCards.tsx
@@ -0,0 +1,133 @@
+import { adminConfigFacts } from "../../lib/api";
+import type { AdminConfigFacts } from "../../lib/types";
+import { useAsyncData } from "../../lib/useAsyncData";
+import { Notice } from "../components";
+import { Surface, Tag } from "../../components/primitives";
+import {
+ memoryTidyRows,
+ quietHoursPurpose,
+ quietHoursRows,
+ quietHoursSummary,
+ type FactRow,
+} from "./configFacts";
+
+/**
+ * 配置**只读事实卡**(切片 P3,契约 v0.68 §4.10(a)):把记忆整理 7 键与安静时段
+ * 的**进程生效值**摊在面板上,用户不必去猜 `.env` 到底有没有生效。
+ *
+ * 它刻意是**只读**:这些键的值来自 `.env`(生产用 systemd/env_file),面板没有
+ * 写回通道,因此不做输入框 —— 那会变成「谎称可调」(与面板既有的诚实边界一致)。
+ * 网关**不读 `.env`**,回的是 `config.Load` 解析后的生效值,所以这里显示的就是
+ * 运行实例真正在用的数。
+ *
+ * 展示与取数刻意分层:`*Body` 只吃数据(可用真实渲染测试直接喂 fixture),
+ * 卡片组件负责取数 + loading/error 呈现。
+ */
+
+/** FactLine 是一行事实:中文说明 + 真键名(mono)+ 生效值 + 「默认/已改/未报告」。 */
+function FactLine({ row }: { row: FactRow }): React.ReactNode {
+ const tone = row.state === "已改" ? "warn" : row.state === "未报告" ? "err" : "neutral";
+ return (
+
+
+ {row.label}
+ {row.key}
+
+
+ {row.value}
+ {row.state}
+
+
+ );
+}
+
+/** FactsLines 渲染一组事实行。 */
+function FactsLines({ rows }: { rows: FactRow[] }): React.ReactNode {
+ return (
+
+ {rows.map((row) => (
+
+ ))}
+
+ );
+}
+
+/** FactsState 统一「读取中 / 读取失败」的呈现(两个卡片共用,避免各写一套)。 */
+function FactsState({ loading, error }: { loading: boolean; error: string | null }): React.ReactNode {
+ if (loading) return 读取配置事实…;
+ if (error) return 读取配置事实失败:{error}(下面的「未报告」因此不代表后端没配);
+ return null;
+}
+
+/** useFacts 拉一次配置事实(两个卡片分属不同页面,各拉各的,互不共享状态)。 */
+function useFacts(): { facts: AdminConfigFacts | null; loading: boolean; error: string | null } {
+ const { data, loading, error } = useAsyncData(() => adminConfigFacts(), []);
+ return { facts: data, loading, error };
+}
+
+/** MemoryTidyFactsBody 是「记忆整理」事实卡的纯展示体(测试直接喂数据)。 */
+export function MemoryTidyFactsBody({ facts }: { facts: AdminConfigFacts | null }): React.ReactNode {
+ if (!facts) return null;
+ return (
+ <>
+
+
+ 整理是低峰期的后台任务,只产建议、绝不自动合并 / 删除 / 改写任何记忆,也不推送、不进 chat 上下文。
+ 低峰窗口的写法:两端相等的非 0 钟点 = 关闭窗口;两端都为 0 = 未填(运行时回落到默认 23:00-07:00)。
+ 卡是只读的:改值请编辑 .env 后重启服务。
+
+ >
+ );
+}
+
+/** QuietHoursFactsBody 是「安静时段」事实卡的纯展示体,文案按主人裁决 10 的新语义。 */
+export function QuietHoursFactsBody({ facts }: { facts: AdminConfigFacts | null }): React.ReactNode {
+ if (!facts) return null;
+ return (
+ <>
+
+ {quietHoursSummary(facts.quietHours)}
+
+ {facts.quietHours.disabled ? "窗口关闭" : "窗口生效"}
+
+
+
+ {quietHoursPurpose()}
+
+ 只读事实(值 = 进程生效值,不是 .env 原文):改窗口请编辑{" "}
+ QUIET_START_HOUR / QUIET_END_HOUR 后重启服务。
+
+ >
+ );
+}
+
+/** 记忆管理页的「记忆整理」只读事实卡。 */
+export function MemoryTidyFactsCard(): React.ReactNode {
+ const { facts, loading, error } = useFacts();
+ return (
+
+
+
记忆整理(只读事实)
+ 进程生效值
+ GET /api/v1/admin/config-facts
+
+
+
+
+ );
+}
+
+/** 后台思考页的「安静时段」只读事实卡。 */
+export function QuietHoursFactsCard(): React.ReactNode {
+ const { facts, loading, error } = useFacts();
+ return (
+
+
+
安静时段(只读事实)
+ 进程生效值
+
+
+
+
+ );
+}
diff --git a/frontend/web/src/admin/modules/Memories.tsx b/frontend/web/src/admin/modules/Memories.tsx
index 2cba554..7d1245d 100644
--- a/frontend/web/src/admin/modules/Memories.tsx
+++ b/frontend/web/src/admin/modules/Memories.tsx
@@ -6,6 +6,7 @@ import { useAutoReload } from "../hooks";
import { useAuditStore } from "../audit";
import { AdminTable, Notice, PageHeader, type AdminColumn } from "../components";
import { Button, Surface, Tag } from "../../components/primitives";
+import { MemoryTidyFactsCard } from "./ConfigFactsCards";
const scopeTone: Record = {
user: "accent",
@@ -184,6 +185,8 @@ export function MemoriesModule(): React.ReactNode {
+
+
编辑 / 删除 / 衰减 / 溯源为后端 M10+ 提供,当前只读 + 手动添加 + 检索测试。群聊 / 陌生人会话查记忆时只读不写、不入主会话上下文、不泄露主人敏感信息。
diff --git a/frontend/web/src/admin/modules/System.tsx b/frontend/web/src/admin/modules/System.tsx
index adc3feb..56779b3 100644
--- a/frontend/web/src/admin/modules/System.tsx
+++ b/frontend/web/src/admin/modules/System.tsx
@@ -165,8 +165,12 @@ export function SystemModule(): React.ReactNode {
- 以上为 .env.example 的默认值(面板无 env 读取端点,不是运行实例的实时值);
- 改值请编辑 .env 后重启服务。
+ 以上为 .env.example 的默认值(这几条没有只读读取端点,不是运行实例的实时值;
+ 带凭据的键面板刻意不回值)。改值请编辑 .env 后重启服务。
+
+
+ 要看运行实例的实时生效值,去两处只读事实卡:记忆管理页的「记忆整理」与后台思考页的「安静时段」
+ (GET /api/v1/admin/config-facts,契约 v0.68)。
diff --git a/frontend/web/src/admin/modules/backthinkUrgency.ts b/frontend/web/src/admin/modules/backthinkUrgency.ts
new file mode 100644
index 0000000..1cd5f6f
--- /dev/null
+++ b/frontend/web/src/admin/modules/backthinkUrgency.ts
@@ -0,0 +1,62 @@
+import type { BackthinkItem } from "../../lib/types";
+
+/**
+ * 后台思考行「紧急度 / 穿透安静时段」标记的**纯逻辑**(契约 v0.68 §4.10(b))。
+ *
+ * 后端 `urgency` 的语义是**存档可证的档位下限**(`warning` = 至少 high 档,可能更
+ * 高),不是精确档位;而窗口之外的轮次存档里没有档位,键**缺席**。因此本层:
+ * - 缺席 ⇒ 显示「档位未知」(**不是**「例常」——把未知画成事实就是这次要避免的坑);
+ * - 未知取值 ⇒ 原样显示后端给的词,不猜一个更好听的;
+ * - `quietHoursBypassed` 只在 true 时渲染「穿透安静时段」。
+ */
+
+export type UrgencyTagTone = "ok" | "warn" | "err" | "neutral" | "accent";
+
+export interface UrgencyTag {
+ label: string;
+ tone: UrgencyTagTone;
+ /** 悬停说明(为什么是这个档位 / 为什么未知),给人看的口径。 */
+ hint: string;
+}
+
+/** 档位未知时的标签(键缺席 = 后端没有这个事实)。 */
+export const URGENCY_UNKNOWN_LABEL = "档位未知";
+
+/** 穿透安静时段的标签。 */
+export const QUIET_HOURS_BYPASS_LABEL = "穿透安静时段";
+
+/** urgencyTag 把后端 `urgency` 映射成标签;键缺席时给「档位未知」。 */
+export function urgencyTag(item: Pick): UrgencyTag {
+ const level = item.urgency;
+ switch (level) {
+ case "routine":
+ return { label: "例常", tone: "neutral", hint: "安静时段内被扣下的轮次:档位低于 high,不穿透" };
+ case "warning":
+ return {
+ label: "紧急(≥ 高)",
+ tone: "warn",
+ hint: "安静时段内仍被放行 ⇒ 档位至少 high;记录里无法区分 high 与 critical,故显示下限",
+ };
+ case "critical":
+ return { label: "紧急·安全域", tone: "err", hint: "安全域事件(可穿透工作/忙碌与安静时段)" };
+ case undefined:
+ case "":
+ return {
+ label: URGENCY_UNKNOWN_LABEL,
+ tone: "neutral",
+ hint: "这一轮的档位在存档里不可证(轮次不在安静时段窗口内,记录不保存档位)——不是「例常」",
+ };
+ default:
+ return { label: level, tone: "neutral", hint: "后端给了本面板不认识的档位,原样显示" };
+ }
+}
+
+/** quietHoursBypassTag 只在后端确实标记了穿透时返回标签。 */
+export function quietHoursBypassTag(item: Pick): UrgencyTag | null {
+ if (item.quietHoursBypassed !== true) return null;
+ return {
+ label: QUIET_HOURS_BYPASS_LABEL,
+ tone: "accent",
+ hint: "这一轮落在安静时段窗口内、但仍被放行发出(档位 ≥ high)",
+ };
+}
diff --git a/frontend/web/src/admin/modules/configFacts.test.ts b/frontend/web/src/admin/modules/configFacts.test.ts
new file mode 100644
index 0000000..b78455f
--- /dev/null
+++ b/frontend/web/src/admin/modules/configFacts.test.ts
@@ -0,0 +1,137 @@
+// 配置只读事实面(契约 v0.68 §4.10(a))的**纯逻辑**测试:形状 → 文案的映射。
+// 这里盯的是三条不变量:值只取后端给的生效值、默认/已改只由 isDefault 决定、
+// 后端没给的键如实显示「未报告」而不是编一个 0。
+//
+// 跑法(项目无前端测试运行器,用 vite 自带的 esbuild;见同目录既有测试):
+//
+// cd frontend/web \
+// && ./node_modules/.bin/esbuild src/admin/modules/configFacts.test.ts \
+// --bundle --platform=node --format=esm \
+// --outfile=/tmp/cyrene-config-facts.test.mjs \
+// && node /tmp/cyrene-config-facts.test.mjs
+//
+// `tsc --noEmit`(npm run build 的一部分)会类型检查本文件,因此它不 import node:*。
+
+import type { AdminConfigFacts } from "../../lib/types";
+import {
+ FACT_MISSING_VALUE,
+ MEMORY_TIDY_KEYS,
+ QUIET_HOURS_KEYS,
+ factRows,
+ memoryTidyRows,
+ quietHoursPurpose,
+ quietHoursRows,
+ quietHoursSummary,
+} from "./configFacts";
+
+let checks = 0;
+
+function ok(cond: boolean, what: string): void {
+ checks += 1;
+ if (!cond) throw new Error(`FAILED: ${what}`);
+}
+
+function same(got: T, want: T, what: string): void {
+ ok(
+ JSON.stringify(got) === JSON.stringify(want),
+ `${what} — got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`,
+ );
+}
+
+function has(haystack: string, needle: string): boolean {
+ return haystack.includes(needle);
+}
+
+/** 生效值全为默认的常态响应(后端在默认部署下会这么回)。 */
+const DEFAULTS: AdminConfigFacts = {
+ facts: [
+ { key: "MEMORY_TIDY_ENABLED", value: "true", default: "true", isDefault: true },
+ { key: "MEMORY_TIDY_INTERVAL_SEC", value: "86400", default: "86400", isDefault: true },
+ { key: "MEMORY_TIDY_QUIET_START_HOUR", value: "23", default: "23", isDefault: true },
+ { key: "MEMORY_TIDY_QUIET_END_HOUR", value: "7", default: "7", isDefault: true },
+ { key: "MEMORY_TIDY_RECALL_THRESHOLD", value: "0.8", default: "0.8", isDefault: true },
+ { key: "MEMORY_TIDY_SCAN_LIMIT", value: "5000", default: "5000", isDefault: true },
+ { key: "MEMORY_TIDY_CANDIDATE_LIMIT", value: "20", default: "20", isDefault: true },
+ { key: "QUIET_START_HOUR", value: "23", default: "23", isDefault: true },
+ { key: "QUIET_END_HOUR", value: "7", default: "7", isDefault: true },
+ ],
+ quietHours: { startHour: 23, endHour: 7, disabled: false, label: "23:00-07:00" },
+};
+
+// ── ① 值就是后端给的生效值(含单位),不重算 ─────────────────────────────────
+const tidy = memoryTidyRows(DEFAULTS);
+same(tidy.length, 7, "记忆整理恰好 7 行(后端的 7 个键)");
+same(
+ tidy.map((r) => r.key),
+ [...MEMORY_TIDY_KEYS],
+ "键序与后端事实表一致",
+);
+const interval = tidy.find((r) => r.key === "MEMORY_TIDY_INTERVAL_SEC");
+same(interval?.value, "86400 秒", "周期带单位显示,数值原样取后端");
+same(interval?.state, "默认", "isDefault=true ⇒ 显示「默认」");
+const threshold = tidy.find((r) => r.key === "MEMORY_TIDY_RECALL_THRESHOLD");
+same(threshold?.value, "0.8", "比例值原样显示(后端已归一化)");
+
+// ── ② 「已改」只由 isDefault 决定(不反推 .env) ─────────────────────────────
+const changed: AdminConfigFacts = {
+ ...DEFAULTS,
+ facts: DEFAULTS.facts.map((f) =>
+ f.key === "MEMORY_TIDY_INTERVAL_SEC" ? { ...f, value: "3600", isDefault: false } : f,
+ ),
+};
+const changedRow = memoryTidyRows(changed).find((r) => r.key === "MEMORY_TIDY_INTERVAL_SEC");
+same(changedRow?.value, "3600 秒", "改过的值如实显示");
+same(changedRow?.state, "已改", "isDefault=false ⇒ 显示「已改」");
+same(
+ memoryTidyRows(changed).filter((r) => r.state === "已改").length,
+ 1,
+ "只有真的改过的那一行是「已改」",
+);
+
+// ── ③ 后端没给的键如实显示「未报告」,绝不编值 ──────────────────────────────
+const partial: AdminConfigFacts = {
+ facts: DEFAULTS.facts.filter((f) => f.key !== "MEMORY_TIDY_SCAN_LIMIT"),
+ quietHours: DEFAULTS.quietHours,
+};
+const missing = memoryTidyRows(partial).find((r) => r.key === "MEMORY_TIDY_SCAN_LIMIT");
+same(missing?.value, FACT_MISSING_VALUE, "缺的键显示「未报告」而不是 0 或默认值");
+same(missing?.state, FACT_MISSING_VALUE, "缺的键状态也是「未报告」");
+same(memoryTidyRows(null).length, 7, "整份响应都没拿到时,7 行仍然都在(全为未报告)");
+ok(
+ memoryTidyRows(null).every((r) => r.state === FACT_MISSING_VALUE),
+ "没有响应时不留空白行,全部如实标「未报告」",
+);
+
+// ── ④ 安静时段:窗口摘要 + 用途文案(新语义,不得说「夜间全静默」) ─────────
+same(quietHoursRows(DEFAULTS).map((r) => r.key), [...QUIET_HOURS_KEYS], "安静时段两行");
+same(quietHoursSummary(DEFAULTS.quietHours), "23:00-07:00(跨午夜)", "跨午夜窗口如实标注");
+same(
+ quietHoursSummary({ startHour: 1, endHour: 5, disabled: false, label: "01:00-05:00" }),
+ "01:00-05:00",
+ "非跨午夜窗口不加多余后缀",
+);
+same(
+ quietHoursSummary({ startHour: 23, endHour: 23, disabled: true, label: "已关闭" }),
+ "已关闭(安静时段从不生效)",
+ "窗口关闭必须说「从不生效」,不能画成 23:00-23:00 的假窗口",
+);
+same(
+ quietHoursSummary({ startHour: 23, endHour: 7, disabled: false, label: "23:00-07:00", fallbackToDefault: true }),
+ "23:00-07:00(两端写 0 = 未填,运行时回落到默认窗口)",
+ "0/0 被当成「未填」时必须说明回落,不能谎报成「已关闭」",
+);
+same(quietHoursSummary(null), FACT_MISSING_VALUE, "没有 quietHours 时如实报未报告");
+
+const purpose = quietHoursPurpose();
+ok(has(purpose, "定时主动思考"), "用途文案必须点明它服务「定时主动思考 → 主动搭话」");
+ok(has(purpose, "不静默回复") || has(purpose, "不会因为到了安静时段就被静默"), "用途文案必须说清回复侧不被静默");
+ok(!has(purpose, "夜间全静默"), "不得沿用已废弃的旧语义「夜间全静默」");
+ok(!has(purpose, "群聊静默"), "群聊夜间静默已被取消,不得写成有");
+
+// ── ⑤ factRows 对未知键不崩、原样透出键名 ───────────────────────────────────
+const unknown = factRows(DEFAULTS, ["NOT_A_REAL_KEY"]);
+same(unknown[0].label, "NOT_A_REAL_KEY", "没有元数据的键用键名兜底(不编中文标签)");
+same(unknown[0].value, FACT_MISSING_VALUE, "没有元数据的键如实「未报告」");
+
+// eslint-disable-next-line no-console
+console.log(`configFacts: ${checks} checks passed`);
diff --git a/frontend/web/src/admin/modules/configFacts.ts b/frontend/web/src/admin/modules/configFacts.ts
new file mode 100644
index 0000000..b82948a
--- /dev/null
+++ b/frontend/web/src/admin/modules/configFacts.ts
@@ -0,0 +1,110 @@
+import type { AdminConfigFact, AdminConfigFacts, AdminConfigQuietHours } from "../../lib/types";
+
+/**
+ * 配置只读事实卡的**纯逻辑**(契约 v0.68 §4.10(a))。这里只做形状 → 文案的映射,
+ * 不发请求、不碰 DOM,因此可以用 plain-node 检查跑(见 configFacts.test.ts)。
+ *
+ * 三条不变量(与后端 admin_config_facts.go 同一口径):
+ * 1. 值一律取后端给的**进程生效值**,本层不推算、不格式化数值(只补单位/说明);
+ * 2. 「默认 / 已改」只由 `isDefault` 决定,**不**反推 `.env` 写过什么(面板读不到);
+ * 3. 后端没给的键如实显示「未报告」,**绝不**编一个值出来。
+ */
+
+/** 后端没给这条事实时的显示值(不是 0,也不是默认值)。 */
+export const FACT_MISSING_VALUE = "未报告";
+
+/** 记忆整理的 7 个键(与后端 configFactSpecs 的前 7 条同序)。 */
+export const MEMORY_TIDY_KEYS: readonly string[] = [
+ "MEMORY_TIDY_ENABLED",
+ "MEMORY_TIDY_INTERVAL_SEC",
+ "MEMORY_TIDY_QUIET_START_HOUR",
+ "MEMORY_TIDY_QUIET_END_HOUR",
+ "MEMORY_TIDY_RECALL_THRESHOLD",
+ "MEMORY_TIDY_SCAN_LIMIT",
+ "MEMORY_TIDY_CANDIDATE_LIMIT",
+];
+
+/** 安静时段的两个键(后端事实表后两条)。 */
+export const QUIET_HOURS_KEYS: readonly string[] = ["QUIET_START_HOUR", "QUIET_END_HOUR"];
+
+export interface FactRow {
+ key: string;
+ /** 中文说明(这个键管什么)。 */
+ label: string;
+ /** 显示值(生效值 + 单位)。 */
+ value: string;
+ /** `"默认"` / `"已改"` / `"未报告"`。 */
+ state: string;
+}
+
+interface FactMeta {
+ label: string;
+ /** 值后缀(单位);空串表示不加。 */
+ unit?: string;
+}
+
+const FACT_META: Record = {
+ MEMORY_TIDY_ENABLED: { label: "记忆整理总开关" },
+ MEMORY_TIDY_INTERVAL_SEC: { label: "整理周期", unit: " 秒" },
+ MEMORY_TIDY_QUIET_START_HOUR: { label: "整理低峰窗口起点", unit: " 时" },
+ MEMORY_TIDY_QUIET_END_HOUR: { label: "整理低峰窗口终点", unit: " 时" },
+ MEMORY_TIDY_RECALL_THRESHOLD: { label: "候选召回门(余弦)" },
+ MEMORY_TIDY_SCAN_LIMIT: { label: "每轮扫描上限" },
+ MEMORY_TIDY_CANDIDATE_LIMIT: { label: "每轮候选上限" },
+ QUIET_START_HOUR: { label: "安静时段起点(本地钟点)", unit: " 时" },
+ QUIET_END_HOUR: { label: "安静时段终点(本地钟点)", unit: " 时" },
+};
+
+/** factRows 把后端事实列表按给定键序映射成显示行;缺的键如实标「未报告」。 */
+export function factRows(facts: AdminConfigFacts | null, keys: readonly string[]): FactRow[] {
+ const byKey = new Map();
+ for (const f of facts?.facts ?? []) byKey.set(f.key, f);
+ return keys.map((key) => {
+ const meta = FACT_META[key];
+ const got = byKey.get(key);
+ if (!got) {
+ return {
+ key,
+ label: meta ? meta.label : key,
+ value: FACT_MISSING_VALUE,
+ state: FACT_MISSING_VALUE,
+ };
+ }
+ return {
+ key,
+ label: meta ? meta.label : key,
+ value: `${got.value}${meta?.unit ?? ""}`,
+ state: got.isDefault ? "默认" : "已改",
+ };
+ });
+}
+
+/** 记忆整理事实行(7 条)。 */
+export function memoryTidyRows(facts: AdminConfigFacts | null): FactRow[] {
+ return factRows(facts, MEMORY_TIDY_KEYS);
+}
+
+/** 安静时段事实行(2 条)。 */
+export function quietHoursRows(facts: AdminConfigFacts | null): FactRow[] {
+ return factRows(facts, QUIET_HOURS_KEYS);
+}
+
+/** 安静时段窗口的一句话摘要(后端 label + 跨午夜 / 已关闭 / 「0/0 = 未填」的如实补充)。 */
+export function quietHoursSummary(qh: AdminConfigQuietHours | null | undefined): string {
+ if (!qh) return FACT_MISSING_VALUE;
+ if (qh.disabled) return "已关闭(安静时段从不生效)";
+ const label = qh.label || `${qh.startHour}:00-${qh.endHour}:00`;
+ if (qh.fallbackToDefault) {
+ return `${label}(两端写 0 = 未填,运行时回落到默认窗口)`;
+ }
+ return qh.startHour > qh.endHour ? `${label}(跨午夜)` : label;
+}
+
+/**
+ * 安静时段的**用途文案**(主人裁决 10 的新语义)。
+ * ⚠️ 必须说清「只服务定时主动思考 → 主动搭话,不静默回复」——
+ * 写成「夜间全静默」是已废弃的旧实现语义,被这次改动明确否掉了。
+ */
+export function quietHoursPurpose(): string {
+ return "安静时段只服务「定时主动思考 → 主动搭话」:她在这个窗口里默认不主动找你。回复侧不受它约束——你任何时候说话,她都照常回,不会因为到了安静时段就被静默。群聊同样没有夜间静默。";
+}
diff --git a/frontend/web/src/lib/api.ts b/frontend/web/src/lib/api.ts
index 7d7cb41..dba2c72 100644
--- a/frontend/web/src/lib/api.ts
+++ b/frontend/web/src/lib/api.ts
@@ -113,6 +113,7 @@ export type { ChannelActionResult, ChannelConfigSaveResult } from "./api/adminCh
export {
adminBackthink,
+ adminConfigFacts,
adminListNotifications,
adminObservabilityAudit,
adminObservabilityLogs,
diff --git a/frontend/web/src/lib/api/adminSystem.ts b/frontend/web/src/lib/api/adminSystem.ts
index 600b5d7..66cef7d 100644
--- a/frontend/web/src/lib/api/adminSystem.ts
+++ b/frontend/web/src/lib/api/adminSystem.ts
@@ -7,6 +7,7 @@ import type {
AdminStorageStatus,
AdminTraceSpan,
AuditRecord,
+ AdminConfigFacts,
BackthinkItem,
SystemBackupResp,
SystemRestoreResp,
@@ -45,6 +46,14 @@ export function adminBackthink(limit?: number): Promise {
return request(`/admin/backthink${limitQuery(limit)}`);
}
+/** GET /api/v1/admin/config-facts — **只读**配置事实面(契约 v0.68 §4.10(a)):
+ * 记忆整理 7 键 + 安静时段两键的**进程生效值** + 声明默认值,外加安静时段窗口的
+ * 解释(跨午夜 / 已关闭)。owner/admin 档;**不含任何凭据值**(后端有哨兵测试钉死),
+ * 网关也**不读 `.env`** —— 值就是运行实例真正在用的数。 */
+export function adminConfigFacts(): Promise {
+ return request("/admin/config-facts");
+}
+
/** GET /api/v1/admin/notifications?type=&before=&limit= — the unified notification
* feed (design/10 §3 #16: audit + channel + backthink + system aggregated).
* `type` omitted = all types, `before` = createdAt(ms) cursor for older pages,
diff --git a/frontend/web/src/lib/types.ts b/frontend/web/src/lib/types.ts
index 7278279..1132e75 100644
--- a/frontend/web/src/lib/types.ts
+++ b/frontend/web/src/lib/types.ts
@@ -12,3 +12,4 @@ export * from "./types/admin";
export * from "./types/adminWrite";
export * from "./types/kook";
export * from "./types/notification";
+export * from "./types/configFacts";
diff --git a/frontend/web/src/lib/types/agent.ts b/frontend/web/src/lib/types/agent.ts
index ec48447..a91e9f8 100644
--- a/frontend/web/src/lib/types/agent.ts
+++ b/frontend/web/src/lib/types/agent.ts
@@ -42,7 +42,17 @@ export interface BackthinkItem {
route?: string;
/** 打扰决策或投递的简短原因(后端 PushResult.Detail),例如 quiet hours、无活跃客户端。 */
detail?: string;
- /** 事件驱动推送绕过了限频闸(后端 PushResult.Bypassed,"该发就发")。 */
+ /** 事件驱动推送绕过了限频闸(后端 PushResult.Bypassed,"该发就发")。
+ * ⚠️ 与 `quietHoursBypassed`(安静时段穿透)**是两件事**:这个说的是限频门。 */
bypassed?: boolean;
+ /** 该轮紧急度的**存档可证下限**(后端 `urgency`,`internal/urgency` 档位词汇:
+ * `routine` | `warning` | `critical`)。`warning` 读作「至少 high 档(可能更高)」。
+ * 缺席 = 后端没有这个事实(轮次不在安静时段窗口内时无从反推),**不是**「例常」。
+ * ⚠️ 实时帧走的是 bus 上原始的 `backthink.Record`,它目前**不带**档位 ⇒ 实时行显示
+ * 「档位未知」,重开页面由历史拉取(`GET /admin/backthink`)补齐。 */
+ urgency?: string;
+ /** 该轮**穿透了安静时段**(轮次时间落在安静时段窗口内且该轮判定要推送)。后端只在
+ * `true` 时下发该键;缺席 = 没有这件事,**不等于**「确认没穿透」。 */
+ quietHoursBypassed?: boolean;
at: number;
}
diff --git a/frontend/web/src/lib/types/configFacts.ts b/frontend/web/src/lib/types/configFacts.ts
new file mode 100644
index 0000000..49f496d
--- /dev/null
+++ b/frontend/web/src/lib/types/configFacts.ts
@@ -0,0 +1,33 @@
+// 管理面「配置事实」的线上类型(契约 v0.68 §4.10(a))。
+// 唯一真源:internal/services/gateway/admin_config_facts.go。
+// 后端只回**非敏感调参**(记忆整理 7 键 + 安静时段 2 键)——响应里没有、也不会
+// 有凭据值,因此这里也刻意不存在任何 token / key / secret 字段。
+
+export interface AdminConfigFact {
+ /** env 键名,与 `.env.example` 逐字一致(后端有测试钉住)。 */
+ key: string;
+ /** **进程生效值**(已解析后的值,不是 `.env` 原文)。 */
+ value: string;
+ /** 该键的声明默认值(`internal/config` 的 `default` 标签)。 */
+ default: string;
+ /** 生效值是否等于声明默认值:true 显示「默认」,false 显示「已改」。
+ * ⚠️ 它**不是**「`.env` 没写过这个键」的断言(网关不读 `.env`)。 */
+ isDefault: boolean;
+}
+
+export interface AdminConfigQuietHours {
+ startHour: number;
+ endHour: number;
+ /** 窗口已关闭(两个相等的**非 0** 钟点):此时安静时段**从不生效**。 */
+ disabled: boolean;
+ /** 后端给的显示文案:`"23:00-07:00"` 或 `"已关闭"`。 */
+ label: string;
+ /** 窗口两端都被写成 0 ⇒ 视为「未填」,运行时回落到默认窗口(后端已按回落后的
+ * 钟点填 startHour/endHour)。0/0 **不是**「关闭」——关闭要写两个相等的非 0 值。 */
+ fallbackToDefault?: boolean;
+}
+
+export interface AdminConfigFacts {
+ facts: AdminConfigFact[];
+ quietHours: AdminConfigQuietHours;
+}
diff --git a/frontend/web/src/lib/wsParse.ts b/frontend/web/src/lib/wsParse.ts
index bc953e5..9ea0ad0 100644
--- a/frontend/web/src/lib/wsParse.ts
+++ b/frontend/web/src/lib/wsParse.ts
@@ -301,7 +301,27 @@ export function parseBackthinkItem(v: unknown): BackthinkItem | null {
const detail = firstPushText(pr.Detail, pr.detail, r.detail, r.push_detail);
const bypassedRaw = pr.Bypassed ?? pr.bypassed ?? r.bypassed ?? r.push_bypassed;
const bypassed = typeof bypassedRaw === "boolean" ? bypassedRaw : undefined;
- return { id: String(idRaw), trigger, conclusion, shouldNotify, pushed, route, detail, bypassed, at };
+ // v0.68 的档位/穿透:**防御性读取**(兼容 camelCase 与 Go 字段名)。当前 bus 上发布的
+ // 是原始 `backthink.Record`,它**不带**这两个字段 ⇒ 今天恒为 undefined(本次会话新到
+ // 的行显示「档位未知」,重开页面由历史拉取补真值)。一旦后端把这两个事实放进帧里,
+ // 这里无需改动就会显示出来 —— 但绝不因为「帧里没有」就编一个值。
+ const urgencyRaw = r.urgency ?? r.Urgency ?? r.urgency_level ?? r.urgencyLevel;
+ const urgency = typeof urgencyRaw === "string" && urgencyRaw ? urgencyRaw : undefined;
+ const qhRaw = r.quietHoursBypassed ?? r.QuietHoursBypassed;
+ const quietHoursBypassed = typeof qhRaw === "boolean" ? qhRaw : undefined;
+ return {
+ id: String(idRaw),
+ trigger,
+ conclusion,
+ shouldNotify,
+ pushed,
+ route,
+ detail,
+ bypassed,
+ urgency,
+ quietHoursBypassed,
+ at,
+ };
}
/** 取 PushResult 文本字段的第一个非空值(先 Go 字段名,再 camelCase)。空串按
diff --git a/internal/services/gateway/admin.go b/internal/services/gateway/admin.go
index 2ce2c37..78c7a7a 100644
--- a/internal/services/gateway/admin.go
+++ b/internal/services/gateway/admin.go
@@ -124,6 +124,12 @@ type AdminUserRecord struct {
// design/10 §3 #12)回答「走了哪条路、为什么打扰/为什么不打扰」——
// 它们直接来自后端已存的 PushResult,因此面板不必靠猜来解释
// 一次静默。
+//
+// Urgency / QuietHoursBypassed(v0.68)回答「这一轮有多紧急、是不是
+// 穿透了安静时段」。二者都**只在存档可证时**出现,缺席 ≠ 常规档位:
+// 推导依据见 admin_backthink_urgency.go(那一轮的 `At` 落在安静时段窗口内
+// 时,判定级联已把档位锁死到可证的范围;窗口之外的轮次存档里没有档位,
+// 因此不下发,而不是编一个 routine)。
type AdminBackthinkItem struct {
ID string `json:"id"`
Trigger string `json:"trigger"`
@@ -137,6 +143,14 @@ type AdminBackthinkItem struct {
// Bypassed 表示这是事件驱动的推送、绕过了限频闸("该发就发")。
Bypassed bool `json:"bypassed"`
At int64 `json:"at"`
+ // Urgency 是这一轮紧急度的**存档可证下限**(urgency 档位词汇:
+ // routine | warning | critical)。`warning` 读作「≥ high 档(可能更高)」;
+ // 无法证明时省略该键(面板显示「未知」)。
+ Urgency string `json:"urgency,omitempty"`
+ // QuietHoursBypassed 为 true 时表示这一轮**穿透了安静时段**(轮次时间落在
+ // 安静时段窗口内且该轮判定要推送)。只在为 true 时出现:安静时段之外的轮次
+ // 与「没穿透」不必在线上区分,缺席即「没有这件事」。
+ QuietHoursBypassed bool `json:"quietHoursBypassed,omitempty"`
}
// AdminRagDoc 是管理 RAG 列表中一个知识库文档(项目索引
diff --git a/internal/services/gateway/admin_backthink_urgency.go b/internal/services/gateway/admin_backthink_urgency.go
new file mode 100644
index 0000000..d657d82
--- /dev/null
+++ b/internal/services/gateway/admin_backthink_urgency.go
@@ -0,0 +1,70 @@
+package gateway
+
+import (
+ "time"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/services/backthink"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/urgency"
+)
+
+// 本文件把「这一轮后台思考有多紧急、是不是穿透了安静时段」变成**存档里可证**的
+// 事实(切片 P4)。它刻意只读 `backthink.Record` 已有的字段 —— 本片不动
+// `internal/services/backthink/**`(通用紧急度通道的落库属那片的面):
+//
+// - `Record.ShouldPush` 是那一轮的打扰判定结果;
+// - `Record.At` 是那一轮的墙钟时间(库里存 UTC,取钟点前必须换回本地
+// 时区,因为安静时段是**本地钟点**窗口);
+// - 安静时段窗口取**进程生效**的 `QUIET_START_HOUR`/`QUIET_END_HOUR`
+// (`config.Background`,与 backthink 的 cfg 同源:组合根把同一对值交给它)。
+//
+// 由 `backthink.Decide` 的判定级联(`decide.go` 的 baseDecide)可证:
+//
+// - 安静时段内被**放行** ⇒ 该轮重要度必然 ≥ `ImportanceHigh`(更低档位在安静
+// 时段一律被扣下)⇒ 这一轮**穿透了安静时段**,档位**至少**是 `warning`
+// (high)。这就是 `quietHoursBypassed` 的全部依据,不是启发式。
+// - 安静时段内被**扣下** ⇒ 档位 < high ⇒ `routine`,未穿透。
+// - 安静时段**之外** ⇒ 判定根本不看档位(「想不想说」由她自己的结论决定),
+// 并且推送成功的行其 `PushResult.Detail` 已被投递说明覆盖 ⇒ 存档里没有任何
+// 字段能反推档位。此时**不下发** urgency(面板显示「未知」),绝不猜。
+//
+// 因此 `AdminBackthinkItem.Urgency` 的语义是「**存档可证的档位下限**」而不是
+// 「精确档位」:`warning` 读作「≥ high(含 critical)」。要做到精确档位,需要
+// backthink 把每轮的 `Import` 落进 `Record`(本片不做,已在契约 §4.10(c) 与
+// §7.4-17 如实登记)。
+
+// backthinkQuietOutcome 是「该轮与安静时段的关系」的推导结果。
+type backthinkQuietOutcome struct {
+ // urgency 是档位下限标签(urgency.Level 的词汇),无法证明时为空串。
+ urgency string
+ // bypassed 报告该轮是否穿透了安静时段(安静时段内仍被放行)。
+ bypassed bool
+}
+
+// backthinkQuietOutcomeOf 推导一条存档记录可证的紧急度下限与穿透标记。
+//
+// `at` 为零值(时间戳格式错乱的行,见 backthink.store.parseTime 的兜底)时一律
+// 返回「无事实」:宁可不显示,也不把零值时间当成凌晨而谎报一轮穿透。
+func backthinkQuietOutcomeOf(rec backthink.Record, startHour, endHour int) backthinkQuietOutcome {
+ if rec.At.IsZero() {
+ return backthinkQuietOutcome{}
+ }
+ if !quietHoursActiveAt(startHour, endHour, rec.At.Local()) {
+ return backthinkQuietOutcome{}
+ }
+ if rec.ShouldPush {
+ return backthinkQuietOutcome{urgency: urgency.LevelWarning.String(), bypassed: true}
+ }
+ return backthinkQuietOutcome{urgency: urgency.LevelRoutine.String()}
+}
+
+// quietHoursActiveAt 报告 at 是否落在安静时段窗口内。口径与既有三处逐字一致
+// (`backthink.decide.inQuietHours`、`channelbridge` 轻思考门、
+// `memory.TidyConfig.inQuietHours`):窗口是半开的 `[start, end)`,可跨午夜;
+// 两端相等即关闭(`23/23` 与 `0/0` 都得到「从不生效」)。
+func quietHoursActiveAt(startHour, endHour int, at time.Time) bool {
+ h := at.Hour()
+ if startHour <= endHour {
+ return h >= startHour && h < endHour
+ }
+ return h >= startHour || h < endHour
+}
diff --git a/internal/services/gateway/admin_backthink_urgency_test.go b/internal/services/gateway/admin_backthink_urgency_test.go
new file mode 100644
index 0000000..f1775fc
--- /dev/null
+++ b/internal/services/gateway/admin_backthink_urgency_test.go
@@ -0,0 +1,168 @@
+package gateway
+
+import (
+ "net/http"
+ "strings"
+ "testing"
+ "time"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/services/backthink"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/urgency"
+)
+
+// 本文件是 P4「后台思考行紧急度 / 穿透安静时段」的测试:钉住
+// 「穿透标记 ⇔ 档位下限」的对应关系,以及「不可证时不下发」的诚实边界。
+
+// quietCfg 构造安静时段 = 23:00-07:00(跨午夜)的生效配置。
+func quietCfg() *config.Config {
+ cfg := cfgDefault()
+ cfg.Background.QuietStartHour = 23
+ cfg.Background.QuietEndHour = 7
+ return cfg
+}
+
+// localAt 造一个**本地时区**的墙钟时刻(安静时段是本地钟点窗口)。
+func localAt(hour int) time.Time {
+ return time.Date(2026, 10, 6, hour, 30, 0, 0, time.Local)
+}
+
+// TestAdminBackthink_QuietHoursBypassMatchesUrgency 是判据 ④:管理行上的穿透标记
+// 必须与 `urgency` 档位下限一一对应 ——
+// - 安静时段内 + 判定要推 → urgency=warning(≥ high)+ quietHoursBypassed=true;
+// - 安静时段内 + 判定不推 → urgency=routine + 无穿透键;
+// - 安静时段外 → 两个键都不下发(存档不可证,绝不猜)。
+func TestAdminBackthink_QuietHoursBypassMatchesUrgency(t *testing.T) {
+ t.Parallel()
+ feed := &stubBackthinkFeed{records: []backthink.Record{
+ {
+ ID: 3, Trigger: "iot.device.smoke", At: localAt(2), Conclusion: "烟雾告警,得叫她",
+ ShouldPush: true,
+ PushResult: backthink.PushResult{Pushed: true, Route: backthink.RouteActiveClient, Bypassed: true, Detail: "delivered to 1 active client(s), event_bypass"},
+ },
+ {
+ ID: 2, Trigger: "heartbeat", At: localAt(3), Conclusion: "深夜只是想一想",
+ ShouldPush: false,
+ PushResult: backthink.PushResult{Route: backthink.RouteNone, Detail: "quiet hours; not interrupting"},
+ },
+ {
+ ID: 1, Trigger: "heartbeat", At: localAt(12), Conclusion: "白天的一轮",
+ ShouldPush: true,
+ PushResult: backthink.PushResult{Pushed: true, Route: backthink.RouteIMBridge, Detail: "delivered via IM bridge"},
+ },
+ }}
+ _, ts, jwt := buildEnv(t, quietCfg(), Deps{Backthink: feed})
+ status, raw, items := listBackthinkItems(t, ts, signAny(t, jwt, "acct", auth.RoleOwner))
+ if status != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", status, raw)
+ }
+ if len(items) != 3 {
+ t.Fatalf("items = %d, want 3", len(items))
+ }
+ body := string(raw)
+ byID := map[string]AdminBackthinkItem{}
+ for _, it := range items {
+ byID[it.ID] = it
+ }
+ // ① 安静时段内被放行 ⇒ 穿透 + 档位下限 warning(= 至少 high)。
+ bypass := byID["3"]
+ if !bypass.QuietHoursBypassed || bypass.Urgency != urgency.LevelWarning.String() {
+ t.Fatalf("穿透行 = %+v, want urgency=%s + quietHoursBypassed=true", bypass, urgency.LevelWarning)
+ }
+ // ② 安静时段内被扣下 ⇒ routine,且不得标成穿透。
+ held := byID["2"]
+ if held.QuietHoursBypassed || held.Urgency != urgency.LevelRoutine.String() {
+ t.Fatalf("静默行 = %+v, want urgency=routine 且不穿透", held)
+ }
+ // ③ 安静时段之外 ⇒ 两个键都不下发(存档不可证)。
+ day := byID["1"]
+ if day.QuietHoursBypassed || day.Urgency != "" {
+ t.Fatalf("白天行 = %+v, want 两个键都缺席", day)
+ }
+ // 线上形状:真穿透的行必须带这两个键;不可证的行必须**不带**它们(不是 false)。
+ if !strings.Contains(body, `"urgency":"warning"`) || !strings.Contains(body, `"quietHoursBypassed":true`) {
+ t.Fatalf("响应缺少穿透/档位键:%s", body)
+ }
+ if !strings.Contains(body, `"urgency":"routine"`) {
+ t.Fatalf("响应缺少被扣下那轮的档位:%s", body)
+ }
+ if strings.Contains(body, `"quietHoursBypassed":false`) {
+ t.Fatalf("「没穿透」不得写成 false(键必须缺席,才不把「未知」画成事实):%s", body)
+ }
+}
+
+// TestAdminBackthink_OmitsUrgencyForZeroTimestamp 钉住兜底:时间戳坏掉的行
+// (backthink 存储层解析失败会给零值时间)**不下发**任何档位/穿透 ——
+// 宁可不显示,也不把零值时间当成凌晨而谎报一轮穿透。
+func TestAdminBackthink_OmitsUrgencyForZeroTimestamp(t *testing.T) {
+ t.Parallel()
+ feed := &stubBackthinkFeed{records: []backthink.Record{
+ {ID: 1, Trigger: "broken", ShouldPush: true},
+ }}
+ _, ts, jwt := buildEnv(t, quietCfg(), Deps{Backthink: feed})
+ status, raw, items := listBackthinkItems(t, ts, signAny(t, jwt, "acct", auth.RoleOwner))
+ if status != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", status, raw)
+ }
+ got := items[0]
+ if got.Urgency != "" || got.QuietHoursBypassed {
+ t.Fatalf("零值时间戳不得产出档位/穿透:%+v", got)
+ }
+ if strings.Contains(string(raw), `"urgency"`) || strings.Contains(string(raw), `"quietHoursBypassed"`) {
+ t.Fatalf("零值时间戳必须省略两个键:%s", raw)
+ }
+}
+
+// TestQuietHoursActiveAt_WindowSemantics 钉住窗口口径(与 backthink.decide 的
+// inQuietHours 逐字一致):半开区间、可跨午夜、两端相等即关闭。
+func TestQuietHoursActiveAt_WindowSemantics(t *testing.T) {
+ t.Parallel()
+ at := func(hour, minute int) time.Time {
+ return time.Date(2026, 10, 6, hour, minute, 0, 0, time.Local)
+ }
+ cases := []struct {
+ name string
+ start, end int
+ when time.Time
+ want bool
+ }{
+ {"跨午夜:起点", 23, 7, at(23, 0), true},
+ {"跨午夜:午前", 23, 7, at(2, 30), true},
+ {"跨午夜:终点前", 23, 7, at(6, 59), true},
+ {"跨午夜:终点(半开区间不含)", 23, 7, at(7, 0), false},
+ {"跨午夜:起点前", 23, 7, at(22, 59), false},
+ {"跨午夜:白天", 23, 7, at(12, 0), false},
+ {"日间窗口", 9, 17, at(10, 0), true},
+ {"日间窗口:窗口外", 9, 17, at(22, 0), false},
+ {"两端相等 ⇒ 关闭", 23, 23, at(23, 30), false},
+ {"零值 ⇒ 关闭", 0, 0, at(1, 0), false},
+ }
+ for _, tc := range cases {
+ tc := tc
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+ if got := quietHoursActiveAt(tc.start, tc.end, tc.when); got != tc.want {
+ t.Fatalf("quietHoursActiveAt(%d,%d,%v) = %v, want %v", tc.start, tc.end, tc.when, got, tc.want)
+ }
+ })
+ }
+}
+
+// TestBackthinkQuietOutcomeOf_ReadsLocalHour 钉住时区口径:库里存 UTC,但安静
+// 时段是**本地钟点**窗口 ⇒ 推导必须先换回本地时区再取钟点(否则北京时间凌晨 2 点
+// 会被当成 UTC 18 点,穿透标记整片错位)。
+func TestBackthinkQuietOutcomeOf_ReadsLocalHour(t *testing.T) {
+ t.Parallel()
+ if _, offset := time.Now().In(time.Local).Zone(); offset == 0 {
+ t.Skip("本机 UTC:时区换算在这种环境下不可观测")
+ }
+ local2am := localAt(2)
+ utc := local2am.UTC()
+ if utc.Hour() == local2am.Hour() {
+ t.Skip("本机 UTC:时区换算在这种环境下不可观测")
+ }
+ if got := backthinkQuietOutcomeOf(backthink.Record{At: utc, ShouldPush: true}, 23, 7); !got.bypassed {
+ t.Fatalf("UTC 存储的本地凌晨 2 点必须判为穿透:%+v", got)
+ }
+}
diff --git a/internal/services/gateway/admin_config_defaults.go b/internal/services/gateway/admin_config_defaults.go
new file mode 100644
index 0000000..4a3e57c
--- /dev/null
+++ b/internal/services/gateway/admin_config_defaults.go
@@ -0,0 +1,107 @@
+package gateway
+
+import (
+ "reflect"
+ "strconv"
+ "strings"
+)
+
+// 本文件从 `internal/config` 的 env 标签里读出各键的**声明默认值**,供只读配置
+// 事实面(admin_config_facts.go)如实展示「默认 / 已改」。
+//
+// 为什么用标签而不是另一份默认值清单:`default:"…"` 标签本身就是配置层的唯一
+// 真源(`config.lookupRaw` 在进程环境与 `.env` 都没给值时正是用它)。网关再抄
+// 一份等于制造第二份事实,两边迟早对不上;而反射读标签既不需要 fopen `.env`
+// (主人红线:键名单读 `.env.example`,**绝不读 `.env`**),也不需要新增配置包
+// 导出面。
+
+// envTagName 与 config 包的内部约定一致:env 标签可带逗号分隔的选项,
+// 变量名是逗号前的部分。
+func envTagName(tag string) string {
+ name, _, _ := strings.Cut(tag, ",")
+ return strings.TrimSpace(name)
+}
+
+// declaredEnvDefaults 遍历配置结构体,返回 `env:"KEY"` 字段的声明默认值
+// (`default:"…"` 标签),按字段类型归一化成字符串,键与取值口径与
+// `buildConfigFacts` 对齐:
+//
+// - bool → "true"/"false"(标签里的写法大小写、多余空白都被吸收);
+// - int → 十进制;
+// - float → 归一化小数(`0.80` ⇒ `0.8`);
+// - string→ 原样(去首尾空白)。
+//
+// 没有 `default` 标签的字段不进表(其「未设置」语义由各自的 Set 标志单独表达,
+// 不是本事实面的内容);无法归一化的值原样保留,宁可显示原始文本也不猜。
+func declaredEnvDefaults(root any) map[string]string {
+ out := make(map[string]string)
+ if root == nil {
+ return out
+ }
+ collectEnvDefaults(reflect.ValueOf(root), out, 0)
+ return out
+}
+
+// maxConfigDepth 是递归下探嵌套配置组的深度上限(防御性:配置是静态结构,
+// 但它必须是常量而不是魔法数字)。
+const maxConfigDepth = 8
+
+// collectEnvDefaults 递归收集默认值。非结构体、指针、不可寻址的字段一律跳过:
+// 配置结构体是静态的平面嵌套,够不到的东西不猜。
+func collectEnvDefaults(v reflect.Value, out map[string]string, depth int) {
+ if depth > maxConfigDepth {
+ return
+ }
+ if v.Kind() == reflect.Pointer {
+ if v.IsNil() {
+ return
+ }
+ v = v.Elem()
+ }
+ if v.Kind() != reflect.Struct {
+ return
+ }
+ t := v.Type()
+ for i := 0; i < t.NumField(); i++ {
+ field := t.Field(i)
+ if !field.IsExported() {
+ continue
+ }
+ fv := v.Field(i)
+ tag, hasEnv := field.Tag.Lookup("env")
+ if !hasEnv {
+ // 没有 env 标签的字段是嵌套配置组。
+ collectEnvDefaults(fv, out, depth+1)
+ continue
+ }
+ name := envTagName(tag)
+ if name == "" {
+ continue
+ }
+ def, hasDefault := field.Tag.Lookup("default")
+ if !hasDefault {
+ continue
+ }
+ out[name] = normalizeDefault(fv.Kind(), def)
+ }
+}
+
+// normalizeDefault 把标签里的默认值按字段类型归一化,形状与事实面的生效值一致。
+func normalizeDefault(kind reflect.Kind, raw string) string {
+ text := strings.TrimSpace(raw)
+ switch kind {
+ case reflect.Bool:
+ if b, err := strconv.ParseBool(strings.ToLower(text)); err == nil {
+ return strconv.FormatBool(b)
+ }
+ case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+ if n, err := strconv.ParseInt(text, 10, 64); err == nil {
+ return strconv.FormatInt(n, 10)
+ }
+ case reflect.Float32, reflect.Float64:
+ if f, err := strconv.ParseFloat(text, 64); err == nil {
+ return formatRatio(f)
+ }
+ }
+ return text
+}
diff --git a/internal/services/gateway/admin_config_facts.go b/internal/services/gateway/admin_config_facts.go
new file mode 100644
index 0000000..d1f18f9
--- /dev/null
+++ b/internal/services/gateway/admin_config_facts.go
@@ -0,0 +1,232 @@
+package gateway
+
+import (
+ "net/http"
+ "strconv"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+)
+
+// 本文件承载 P3「配置只读事实面」:把面板此前**看不见、只能照模板猜**的一组调参
+// 键做成只读事实展示(记忆整理 7 键 + 安静时段 2 键)。三条边界(AGENTS §10 与
+// 主人红线):
+//
+// 1. **键名单的权威来源是 `.env.example`**(不是 `.env`、也不是本文件自己发明
+// 一份清单):事实表逐条与模板键名对齐,由
+// `TestAdminConfigFacts_KeysMatchEnvExample` 钉住;加了键却忘了同步模板会被
+// 这条测试打红(协同 E6 的同一类固定动作)。
+// 2. **值只取「进程生效值」**:即 `config.Load` 解析后的字段(进程环境 → `.env`
+// → 默认标签的优先级链已经由配置层消化)。网关**绝不 fopen `.env`**,因此
+// 面板看到的是运行实例真正在用的数,而不是 `.env` 原文。每条事实另带**声明
+// 默认值**(从 `default:"…"` 标签反射读出)与 `isDefault`,于是「这项还是默认
+// 值」与「这项被改过」都能如实显示,不必假装知道 `.env` 里写过什么。
+// 3. **绝不回任何密钥 / 令牌值**:本端点只覆盖上述 9 个非敏感调参键,响应里连
+// 凭据类键的「是否已配置」都不出现。
+// `TestAdminConfigFacts_NeverLeaksSecretValues` 用哨兵值把这条钉死。
+//
+// 安静时段的**语义**(面板文案必须照此写):它**只服务「定时主动思考 → 主动搭话」**,
+// **不静默回复**(design/12 §6 策略五;主人裁决 10)。所以这里只报「窗口是多少、
+// 是否被关掉」,绝不在契约或文案里说「夜间全静默」。
+
+// AdminConfigFact 是一条只读「配置事实」:键名 + 进程生效值 + 声明默认值。
+//
+// Value 与 Default 都是**归一化后的字符串**(bool → "true"/"false",整数 →
+// 十进制,比例 → 归一化小数如 "0.8"),因为面板把它当文本显示,且归一化后
+// 「生效值 == 声明默认值」才是一次可靠的比较。
+type AdminConfigFact struct {
+ Key string `json:"key"`
+ // Value 是进程生效值(已解析),不是 `.env` 原文。
+ Value string `json:"value"`
+ // Default 是该键的声明默认值(internal/config 的 default 标签,唯一真源)。
+ Default string `json:"default"`
+ // IsDefault 报告生效值是否等于声明默认值。它为 true 时面板显示「默认」;
+ // 为 false 时显示「已改」。**它不是**「`.env` 没写过这个键」的断言 ——
+ // 本端点不读 `.env`,两者不可区分,因此不做那个更强的声称。
+ IsDefault bool `json:"isDefault"`
+}
+
+// AdminConfigQuietHours 是安静时段窗口的**解释**(不是新配置):两个裸钟点不足以
+// 表达「跨午夜」「已关闭」与「两端写 0 视为未填」,而面板文案需要这些结论。
+type AdminConfigQuietHours struct {
+ StartHour int `json:"startHour"`
+ EndHour int `json:"endHour"`
+ Disabled bool `json:"disabled"`
+ // Label 是可直接显示的窗口文案("23:00-07:00" 或 "已关闭")。
+ Label string `json:"label"`
+ // FallbackToDefault 报告窗口两端都被写成 0。0/0 是**未填**而不是**关闭**:
+ // backthink(cfg.go normalize)与记忆整理(tidy_config.go normalizeTidyConfig)
+ // 都会在这个形状上回落到设计默认 23:00-07:00,因此这里的 StartHour/EndHour
+ // 报的是**回落之后真正生效**的钟点,面板要把这层解释显示出来 —— 否则事实面会把
+ // 「未填」谎报成「已关闭」。要关窗口请写两个相等的**非 0** 钟点(如 23/23)。
+ FallbackToDefault bool `json:"fallbackToDefault,omitempty"`
+}
+
+// AdminConfigFacts 是 GET /api/v1/admin/config-facts 的线上结构。
+type AdminConfigFacts struct {
+ Facts []AdminConfigFact `json:"facts"`
+ QuietHours AdminConfigQuietHours `json:"quietHours"`
+}
+
+// 安静时段关闭时的展示文案(窗口两端相等即关闭,见 quietHoursWindow)。
+const quietHoursDisabledLabel = "已关闭"
+
+// configFactSpec 是一条事实的取数说明:env 键名 + 从生效配置里取值。
+type configFactSpec struct {
+ key string
+ value func(cfg *config.Config) string
+}
+
+// configFactSpecs 是事实表的**唯一真源**:顺序即面板显示顺序(先记忆整理,
+// 后安静时段)。键名必须与 `.env.example` 逐字一致(测试钉住)。
+func configFactSpecs() []configFactSpec {
+ return []configFactSpec{
+ {"MEMORY_TIDY_ENABLED", func(c *config.Config) string {
+ return strconv.FormatBool(c.MemoryTidy.Enabled)
+ }},
+ {"MEMORY_TIDY_INTERVAL_SEC", func(c *config.Config) string {
+ return strconv.Itoa(c.MemoryTidy.IntervalSec)
+ }},
+ {"MEMORY_TIDY_QUIET_START_HOUR", func(c *config.Config) string {
+ return strconv.Itoa(c.MemoryTidy.QuietStartHour)
+ }},
+ {"MEMORY_TIDY_QUIET_END_HOUR", func(c *config.Config) string {
+ return strconv.Itoa(c.MemoryTidy.QuietEndHour)
+ }},
+ {"MEMORY_TIDY_RECALL_THRESHOLD", func(c *config.Config) string {
+ return formatRatio(c.MemoryTidy.RecallThreshold)
+ }},
+ {"MEMORY_TIDY_SCAN_LIMIT", func(c *config.Config) string {
+ return strconv.Itoa(c.MemoryTidy.ScanLimit)
+ }},
+ {"MEMORY_TIDY_CANDIDATE_LIMIT", func(c *config.Config) string {
+ return strconv.Itoa(c.MemoryTidy.CandidateLimit)
+ }},
+ {"QUIET_START_HOUR", func(c *config.Config) string {
+ return strconv.Itoa(c.Background.QuietStartHour)
+ }},
+ {"QUIET_END_HOUR", func(c *config.Config) string {
+ return strconv.Itoa(c.Background.QuietEndHour)
+ }},
+ }
+}
+
+// formatRatio 把比例值归一化成与 declaredEnvDefaults 相同的形状,使
+// 「生效值 == 声明默认值」的比较不受写法影响(标签写 `0.80`、值算出来 `0.8`)。
+func formatRatio(v float64) string {
+ return strconv.FormatFloat(v, 'g', -1, 64)
+}
+
+// buildConfigFacts 组装配置事实面。它是纯函数(不读文件、不读 env),因此可
+// 直接单测;cfg 为 nil 时回退到一个零值配置(此时 9 条事实全部照实报零值 +
+// 声明默认值,面板会看到 isDefault=false 的「已改」而不是一个编出来的值)。
+func buildConfigFacts(cfg *config.Config) AdminConfigFacts {
+ if cfg == nil {
+ cfg = &config.Config{}
+ }
+ defaults := declaredEnvDefaults(cfg)
+ specs := configFactSpecs()
+ out := AdminConfigFacts{Facts: make([]AdminConfigFact, 0, len(specs))}
+ for _, spec := range specs {
+ value := spec.value(cfg)
+ def := defaults[spec.key]
+ out.Facts = append(out.Facts, AdminConfigFact{
+ Key: spec.key,
+ Value: value,
+ Default: def,
+ IsDefault: def != "" && value == def,
+ })
+ }
+ out.QuietHours = quietHoursFacts(cfg.Background.QuietStartHour, cfg.Background.QuietEndHour, defaults)
+ return out
+}
+
+// effectiveQuietHours 返回**运行时真正生效**的安静时段钟点,并报告是否发生了
+// 「未填 → 默认」的回落:
+//
+// - 两端相等且非 0 ⇒ 窗口关闭(既有三处同口径),返回原来的钟点;
+// - 两端都为 0 ⇒ **未填**:组合根把 `config.Background` 交给 backthink,而
+// backthink(cfg.go 的 normalize)与记忆整理(tidy_config.go 的
+// normalizeTidyConfig)都会在 0/0 上回落到设计默认 23:00-07:00。事实面与
+// 后台思考行的事实推导都必须按**回落之后**的窗口算,否则会把「未填」当成
+// 「没有安静时段」,从而漏报真正的穿透。回落值取**声明默认值**(env 标签),
+// 与事实行的 default 同源,不另抄一份常量。
+//
+// defaults 是 declaredEnvDefaults 的结果;缺值(或非法)时如实**不回落**,让调用方
+// 看到原始值,而不是编一个 23 点窗口。
+func effectiveQuietHours(cfg *config.Config, defaults map[string]string) (start, end int, fell bool) {
+ if cfg == nil {
+ return 0, 0, false
+ }
+ return normalizeQuietHours(cfg.Background.QuietStartHour, cfg.Background.QuietEndHour, defaults)
+}
+
+// normalizeQuietHours 是上面那条回落规则的纯函数内核(0/0 ⇒ 用声明默认)。
+func normalizeQuietHours(start, end int, defaults map[string]string) (int, int, bool) {
+ if start != 0 || end != 0 {
+ return start, end, false
+ }
+ ds, okS := parseHourDefault(defaults["QUIET_START_HOUR"])
+ de, okE := parseHourDefault(defaults["QUIET_END_HOUR"])
+ if !okS || !okE {
+ return start, end, false
+ }
+ return ds, de, true
+}
+
+// effectiveQuietHours 是 Server 侧取生效窗口的便捷入口(后台思考行的事实推导与
+// 配置事实面共用同一口径,避免两处漂移)。
+func (s *Server) effectiveQuietHours() (int, int) {
+ start, end, _ := effectiveQuietHours(s.cfg, declaredEnvDefaults(s.cfg))
+ return start, end
+}
+
+// quietHoursFacts 把生效窗口解释成线上结构(跨午夜 / 已关闭 / 是否回落)。
+func quietHoursFacts(start, end int, defaults map[string]string) AdminConfigQuietHours {
+ effStart, effEnd, fell := normalizeQuietHours(start, end, defaults)
+ out := AdminConfigQuietHours{StartHour: effStart, EndHour: effEnd, FallbackToDefault: fell}
+ // 关闭 = 两个相等的非 0 钟点(回落之后不可能出现 0/0,所以不必再特判)。
+ out.Disabled = !fell && effStart == effEnd && effStart != 0
+ if out.Disabled {
+ out.Label = quietHoursDisabledLabel
+ } else {
+ out.Label = formatHour(effStart) + "-" + formatHour(effEnd)
+ }
+ return out
+}
+
+// parseHourDefault 解析声明默认值里的钟点;缺失或不合法时如实报「不知道」
+// (调用方据此不做回落,而不是编一个 0 点窗口)。
+func parseHourDefault(raw string) (int, bool) {
+ if raw == "" {
+ return 0, false
+ }
+ hour, err := strconv.Atoi(raw)
+ if err != nil {
+ return 0, false
+ }
+ return hour, true
+}
+
+// formatHour 把钟点格式化成 "HH:00"(面板文案用)。
+func formatHour(hour int) string {
+ if hour < 0 {
+ hour = 0
+ }
+ return pad2(hour) + ":00"
+}
+
+// pad2 把 0..99 补成两位;三位及以上的值原样返回(配置非法时也不吞掉信息)。
+func pad2(n int) string {
+ if n >= 0 && n < 10 {
+ return "0" + strconv.Itoa(n)
+ }
+ return strconv.Itoa(n)
+}
+
+// adminConfigFacts 是 GET /api/v1/admin/config-facts 的处理函数:只读、不审计、
+// 不读 `.env`、不回凭据。它与消费它的两个面板页(记忆管理、后台思考)同门
+// (owner/admin),因为它们是**面板配置事实**,与 `/admin/memories`、`/admin/llm`
+// 同一档,而不是给 viewer 的运行时监控投影。
+func (s *Server) adminConfigFacts(w http.ResponseWriter, _ *http.Request) {
+ writeJSON(w, http.StatusOK, buildConfigFacts(s.cfg))
+}
diff --git a/internal/services/gateway/admin_config_facts_test.go b/internal/services/gateway/admin_config_facts_test.go
new file mode 100644
index 0000000..5a08b9c
--- /dev/null
+++ b/internal/services/gateway/admin_config_facts_test.go
@@ -0,0 +1,312 @@
+package gateway
+
+import (
+ "encoding/json"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+)
+
+// 本文件是 P3「配置只读事实面」的测试。四条被钉住的判据:
+// ① 安静时段的**值** = 进程生效值(不是常量、不是模板默认);
+// ② 「未配置/默认」如实呈现(value + default + isDefault 三者合起来不伪造事实);
+// ③ 响应里**不含任何密钥/令牌值**(红线,用哨兵值钉死);
+// ④ 键名单 = `.env.example`(键名单的权威来源,协同 E6 的固定动作)。
+
+// getConfigFacts 调用管理端点并返回状态码、原始响应体与解码结果。
+func getConfigFacts(t *testing.T, cfg *config.Config, tok string) (int, []byte, AdminConfigFacts) {
+ t.Helper()
+ _, ts, jwt := buildEnv(t, cfg, Deps{})
+ token := tok
+ if token == "" {
+ token = signAny(t, jwt, "acct", auth.RoleOwner)
+ }
+ resp, raw := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/config-facts", nil, token)
+ var out struct {
+ Data AdminConfigFacts `json:"data"`
+ }
+ if resp.StatusCode == http.StatusOK {
+ if err := json.Unmarshal(raw, &out); err != nil {
+ t.Fatalf("decode: %v (%s)", err, raw)
+ }
+ }
+ return resp.StatusCode, raw, out.Data
+}
+
+// factByKey 取出某键的事实(不存在 ⇒ 测试失败)。
+func factByKey(t *testing.T, facts []AdminConfigFact, key string) AdminConfigFact {
+ t.Helper()
+ for _, f := range facts {
+ if f.Key == key {
+ return f
+ }
+ }
+ t.Fatalf("fact %s missing from %+v", key, facts)
+ return AdminConfigFact{}
+}
+
+// quietHoursCfg 构造一个「安静时段 = 01:00-05:00、记忆整理阈值被改过」的生效配置:
+// 值全部来自配置字段,因此它模拟的正是 `config.Load` 解析后的样子。
+func quietHoursCfg() *config.Config {
+ cfg := cfgDefault()
+ cfg.Background.QuietStartHour = 1
+ cfg.Background.QuietEndHour = 5
+ cfg.MemoryTidy = config.MemoryTidyConfig{
+ Enabled: false,
+ IntervalSec: 3600,
+ QuietStartHour: 2,
+ QuietEndHour: 6,
+ RecallThreshold: 0.7,
+ ScanLimit: 10,
+ CandidateLimit: 3,
+ }
+ return cfg
+}
+
+// TestAdminConfigFacts_QuietHoursAreProcessEffective 是判据 ①:端点回的是
+// **进程生效值**(config 字段),而不是模板默认值、更不是写死的常量。
+func TestAdminConfigFacts_QuietHoursAreProcessEffective(t *testing.T) {
+ t.Parallel()
+ status, _, facts := getConfigFacts(t, quietHoursCfg(), "")
+ if status != http.StatusOK {
+ t.Fatalf("status = %d", status)
+ }
+ if facts.QuietHours.StartHour != 1 || facts.QuietHours.EndHour != 5 {
+ t.Fatalf("quietHours = %+v, want 1..5(进程生效值)", facts.QuietHours)
+ }
+ if facts.QuietHours.Disabled {
+ t.Fatalf("quietHours 1..5 不应被判定为关闭:%+v", facts.QuietHours)
+ }
+ if facts.QuietHours.Label != "01:00-05:00" {
+ t.Fatalf("label = %q, want 01:00-05:00", facts.QuietHours.Label)
+ }
+ for key, want := range map[string]string{
+ "QUIET_START_HOUR": "1",
+ "QUIET_END_HOUR": "5",
+ "MEMORY_TIDY_QUIET_START_HOUR": "2",
+ "MEMORY_TIDY_QUIET_END_HOUR": "6",
+ "MEMORY_TIDY_ENABLED": "false",
+ "MEMORY_TIDY_INTERVAL_SEC": "3600",
+ "MEMORY_TIDY_RECALL_THRESHOLD": "0.7",
+ "MEMORY_TIDY_SCAN_LIMIT": "10",
+ "MEMORY_TIDY_CANDIDATE_LIMIT": "3",
+ } {
+ if got := factByKey(t, facts.Facts, key).Value; got != want {
+ t.Fatalf("%s value = %q, want %q", key, got, want)
+ }
+ }
+ // 被改过的键必须标成「非默认」,面板才知道它不是默认值。
+ if factByKey(t, facts.Facts, "QUIET_START_HOUR").IsDefault {
+ t.Fatal("QUIET_START_HOUR=1 与声明默认 23 不同,isDefault 必须为 false")
+ }
+}
+
+// TestAdminConfigFacts_DeclaredDefaultsAndDefaultFlag 是判据 ②:每条事实都带
+// **声明默认值**(default 标签,非空),且当生效值等于它时 isDefault=true ——
+// 面板因此能如实显示「默认」,而不是把默认值当成「用户配过的值」。
+func TestAdminConfigFacts_DeclaredDefaultsAndDefaultFlag(t *testing.T) {
+ t.Parallel()
+ defaults := map[string]string{
+ "MEMORY_TIDY_ENABLED": "true",
+ "MEMORY_TIDY_INTERVAL_SEC": "86400",
+ "MEMORY_TIDY_QUIET_START_HOUR": "23",
+ "MEMORY_TIDY_QUIET_END_HOUR": "7",
+ "MEMORY_TIDY_RECALL_THRESHOLD": "0.8",
+ "MEMORY_TIDY_SCAN_LIMIT": "5000",
+ "MEMORY_TIDY_CANDIDATE_LIMIT": "20",
+ "QUIET_START_HOUR": "23",
+ "QUIET_END_HOUR": "7",
+ }
+ defaultCfg := &config.Config{
+ MemoryTidy: config.MemoryTidyConfig{
+ Enabled: true, IntervalSec: 86400, QuietStartHour: 23, QuietEndHour: 7,
+ RecallThreshold: 0.8, ScanLimit: 5000, CandidateLimit: 20,
+ },
+ Background: config.BackgroundConfig{QuietStartHour: 23, QuietEndHour: 7},
+ }
+ status, _, facts := getConfigFacts(t, defaultCfg, "")
+ if status != http.StatusOK {
+ t.Fatalf("status = %d", status)
+ }
+ if len(facts.Facts) != len(defaults) {
+ t.Fatalf("facts = %d, want %d", len(facts.Facts), len(defaults))
+ }
+ for key, want := range defaults {
+ got := factByKey(t, facts.Facts, key)
+ if got.Default == "" {
+ t.Fatalf("%s 没有声明默认值:default 标签与事实表漂移了", key)
+ }
+ if got.Default != want {
+ t.Fatalf("%s default = %q, want %q(字面量钉桩)", key, got.Default, want)
+ }
+ if !got.IsDefault || got.Value != want {
+ t.Fatalf("%s 生效值等于默认值时必须 isDefault=true 且 value=%q:%+v", key, want, got)
+ }
+ }
+ // 「已改」的呈现:改一个键,只有它掉出默认。
+ changed := defaultCfg
+ changed.MemoryTidy.RecallThreshold = 0.55
+ _, _, after := getConfigFacts(t, changed, "")
+ got := factByKey(t, after.Facts, "MEMORY_TIDY_RECALL_THRESHOLD")
+ if got.Value != "0.55" || got.IsDefault {
+ t.Fatalf("改过的键必须如实报 value=0.55 且 isDefault=false:%+v", got)
+ }
+ if !factByKey(t, after.Facts, "QUIET_END_HOUR").IsDefault {
+ t.Fatal("未改的键不得被标成「已改」")
+ }
+}
+
+// TestAdminConfigFacts_QuietHoursWindowCanBeDisabled 钉住窗口关闭态的如实呈现
+// (两个相等的**非 0** 钟点):面板必须能显示「已关闭」而不是一个 23:00-23:00 的假窗口。
+func TestAdminConfigFacts_QuietHoursWindowCanBeDisabled(t *testing.T) {
+ t.Parallel()
+ cfg := cfgDefault()
+ cfg.Background.QuietStartHour = 23
+ cfg.Background.QuietEndHour = 23
+ _, _, facts := getConfigFacts(t, cfg, "")
+ if !facts.QuietHours.Disabled || facts.QuietHours.Label != quietHoursDisabledLabel {
+ t.Fatalf("两端相等的窗口必须报「已关闭」:%+v", facts.QuietHours)
+ }
+}
+
+// TestAdminConfigFacts_ZeroZeroQuietHoursFallsBackToDefault 钉住那个容易谎报的边角:
+// 两端都写 0 **不是**「关闭窗口」,而是「未填」—— backthink(cfg.go 的 normalize)与
+// 记忆整理都会回落到设计默认 23:00-07:00。事实面必须报**运行时真正生效**的窗口,否则
+// 会把「未填」谎报成「已关闭」,进而漏报真实发生的穿透。
+func TestAdminConfigFacts_ZeroZeroQuietHoursFallsBackToDefault(t *testing.T) {
+ t.Parallel()
+ cfg := cfgDefault()
+ cfg.Background.QuietStartHour = 0
+ cfg.Background.QuietEndHour = 0
+ _, _, facts := getConfigFacts(t, cfg, "")
+ if facts.QuietHours.Disabled {
+ t.Fatalf("0/0 是「未填」而不是「关闭」:%+v", facts.QuietHours)
+ }
+ if !facts.QuietHours.FallbackToDefault {
+ t.Fatalf("0/0 必须如实报告回落:%+v", facts.QuietHours)
+ }
+ if facts.QuietHours.StartHour != 23 || facts.QuietHours.EndHour != 7 || facts.QuietHours.Label != "23:00-07:00" {
+ t.Fatalf("回落后的生效窗口应为 23:00-07:00:%+v", facts.QuietHours)
+ }
+ // 事实行本身仍如实报「这个键解析出来的值」(0),不替用户改写配置。
+ if got := factByKey(t, facts.Facts, "QUIET_START_HOUR"); got.Value != "0" {
+ t.Fatalf("事实行的 value 必须是该键实际解析出的值:%+v", got)
+ }
+}
+
+// TestEffectiveQuietHours_MatchesBackthinkNormalize 钉住「生效窗口」是同一口径:
+// 非 0 值原样、0/0 才回落。
+func TestEffectiveQuietHours_MatchesBackthinkNormalize(t *testing.T) {
+ t.Parallel()
+ defaults := declaredEnvDefaults(&config.Config{})
+ cases := []struct {
+ name string
+ start, end int
+ wantS int
+ wantE int
+ wantFell bool
+ }{
+ {"常规窗口原样", 1, 5, 1, 5, false},
+ {"跨午夜原样", 23, 7, 23, 7, false},
+ {"相等非 0(关闭)原样", 23, 23, 23, 23, false},
+ {"只有起点为 0 仍是真实窗口", 0, 7, 0, 7, false},
+ {"0/0 视为未填 ⇒ 回落", 0, 0, 23, 7, true},
+ }
+ for _, tc := range cases {
+ tc := tc
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+ cfg := &config.Config{Background: config.BackgroundConfig{QuietStartHour: tc.start, QuietEndHour: tc.end}}
+ gotS, gotE, fell := effectiveQuietHours(cfg, defaults)
+ if gotS != tc.wantS || gotE != tc.wantE || fell != tc.wantFell {
+ t.Fatalf("effectiveQuietHours(%d,%d) = (%d,%d,%v), want (%d,%d,%v)",
+ tc.start, tc.end, gotS, gotE, fell, tc.wantS, tc.wantE, tc.wantFell)
+ }
+ })
+ }
+ // nil 配置不 panic、不编窗口。
+ if s, e, fell := effectiveQuietHours(nil, nil); s != 0 || e != 0 || fell {
+ t.Fatalf("nil 配置必须如实报没有窗口:(%d,%d,%v)", s, e, fell)
+ }
+}
+
+// TestAdminConfigFacts_NeverLeaksSecretValues 是判据 ③(红线):响应体里绝不许
+// 出现任何密钥/令牌值。哨兵值刻意取得足够独特,任何形式的泄漏都会被逮到。
+func TestAdminConfigFacts_NeverLeaksSecretValues(t *testing.T) {
+ t.Parallel()
+ secrets := []string{
+ "jwt-secret-sentinel-0123456789abcdef",
+ "sk-llm-api-key-sentinel",
+ "local-llm-key-sentinel",
+ "embedding-key-sentinel",
+ "postgres://user:pgpassword-sentinel@localhost:5432/cyrene",
+ }
+ cfg := cfgDefault()
+ cfg.Auth.JWTSecret = secrets[0]
+ cfg.Auth.AdminPass = "admin-pass-sentinel"
+ cfg.LLM.APIKey = secrets[1]
+ cfg.LLM.Local.APIKey = secrets[2]
+ cfg.Embedding.APIKey = secrets[3]
+ cfg.DB.PGURL = secrets[4]
+ cfg.Channels = config.ChannelsConfig{
+ AccountsJSON: `{"telegram":[{"id":"conf0","config":{"bot_token":"channel-token-sentinel"}}]}`,
+ }
+
+ status, raw, _ := getConfigFacts(t, cfg, "")
+ if status != http.StatusOK {
+ t.Fatalf("status = %d, body = %s", status, raw)
+ }
+ body := string(raw)
+ for _, secret := range append(secrets, "admin-pass-sentinel", "channel-token-sentinel") {
+ if strings.Contains(body, secret) {
+ t.Fatalf("响应里出现了凭据值 %q —— 这是红线:%s", secret, body)
+ }
+ }
+ // 正对照:非敏感的事实确实在响应里(否则上面那条断言可能只是空响应混过关)。
+ if !strings.Contains(body, `"QUIET_START_HOUR"`) || !strings.Contains(body, `"quietHours"`) {
+ t.Fatalf("响应缺少配置事实本身:%s", body)
+ }
+}
+
+// TestAdminConfigFacts_KeysMatchEnvExample 是判据 ④:键名单的权威来源是
+// `.env.example` —— 9 个键必须逐字出现在模板里(键名写错一个字母,用户照面板
+// 抄去改就是静默不生效,AGENTS §10 的 E6 固定动作)。
+func TestAdminConfigFacts_KeysMatchEnvExample(t *testing.T) {
+ t.Parallel()
+ raw, err := os.ReadFile(filepath.Join("..", "..", "..", ".env.example"))
+ if err != nil {
+ t.Fatalf("read .env.example: %v", err)
+ }
+ template := string(raw)
+ for _, spec := range configFactSpecs() {
+ if !strings.Contains(template, spec.key+"=") {
+ t.Fatalf(".env.example 里没有 %s= —— 事实表与模板漂移", spec.key)
+ }
+ }
+}
+
+// TestAdminConfigFacts_RequiresOwnerOrAdmin 钉住 RBAC 门:可读的是 owner/admin,
+// viewer 拿不到配置事实面(它不是运行时监控投影)。
+func TestAdminConfigFacts_RequiresOwnerOrAdmin(t *testing.T) {
+ t.Parallel()
+ _, ts, jwt := buildEnv(t, cfgDefault(), Deps{})
+ respViewer, _ := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/config-facts", nil, signAny(t, jwt, "acct", auth.RoleViewer))
+ if respViewer.StatusCode != http.StatusForbidden {
+ t.Fatalf("viewer = %d, want 403", respViewer.StatusCode)
+ }
+ for _, role := range []auth.Role{auth.RoleOwner, auth.RoleAdmin} {
+ resp, _ := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/config-facts", nil, signAny(t, jwt, "acct", role))
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("role %s = %d, want 200", role, resp.StatusCode)
+ }
+ }
+ resp, _ := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/config-facts", nil, "")
+ if resp.StatusCode != http.StatusUnauthorized {
+ t.Fatalf("匿名 = %d, want 401", resp.StatusCode)
+ }
+}
diff --git a/internal/services/gateway/admin_query.go b/internal/services/gateway/admin_query.go
index 3cc5b9e..a49bf61 100644
--- a/internal/services/gateway/admin_query.go
+++ b/internal/services/gateway/admin_query.go
@@ -375,7 +375,12 @@ func (s *Server) adminListBackthink(w http.ResponseWriter, r *http.Request) {
writeError(w, apperr.Wrap(apperr.ErrInternal, "backthink_failed", "failed to list backthink records"))
return
}
+ // 安静时段窗口取**运行时真正生效**的那一个(0/0 是「未填」而不是「没有安静时段」,
+ // 见 admin_config_facts.go 的 effectiveQuietHours —— 与 backthink 的 normalize 同口径),
+ // 否则 0/0 部署下会漏报真正的穿透。
+ quietStart, quietEnd := s.effectiveQuietHours()
for _, rec := range records {
+ quiet := backthinkQuietOutcomeOf(rec, quietStart, quietEnd)
out = append(out, AdminBackthinkItem{
ID: strconv.FormatInt(rec.ID, 10),
Trigger: rec.Trigger,
@@ -386,6 +391,9 @@ func (s *Server) adminListBackthink(w http.ResponseWriter, r *http.Request) {
Detail: rec.PushResult.Detail,
Bypassed: rec.PushResult.Bypassed,
At: rec.At.UnixMilli(),
+ // 紧急度下限 / 是否穿透安静时段(v0.68):只报存档可证的部分。
+ Urgency: quiet.urgency,
+ QuietHoursBypassed: quiet.bypassed,
})
}
writeJSON(w, http.StatusOK, out)
diff --git a/internal/services/gateway/routes.go b/internal/services/gateway/routes.go
index 864d05d..8c4d5c7 100644
--- a/internal/services/gateway/routes.go
+++ b/internal/services/gateway/routes.go
@@ -176,6 +176,10 @@ func (s *Server) registerAdminRoutes(
mux.Handle("GET /api/v1/admin/llm/catalog", writeAuth(http.HandlerFunc(s.adminGetLlmCatalog)))
mux.Handle("GET /api/v1/admin/users", writeAuth(http.HandlerFunc(s.adminListUsers)))
mux.Handle("GET /api/v1/admin/backthink", writeAuth(http.HandlerFunc(s.adminListBackthink)))
+ // 配置事实面(切片 P3,**v0.68**):记忆整理 7 键 + 安静时段两键的**进程生效值**
+ // 与声明默认值。只读、不审计、**不读 `.env`**、**不含任何凭据**;与消费它的面板页
+ // (记忆管理 / 后台思考)同门,故走 owner|admin 档而不是 viewer 监控档。
+ mux.Handle("GET /api/v1/admin/config-facts", writeAuth(http.HandlerFunc(s.adminConfigFacts)))
mux.Handle("GET /api/v1/admin/observability/audit", writeAuth(http.HandlerFunc(s.adminObservabilityAudit)))
mux.Handle("GET /api/v1/admin/sessions/{id}/export", writeAuth(http.HandlerFunc(s.adminExportSession)))
mux.Handle("POST /api/v1/admin/rag/query", writeAuth(http.HandlerFunc(s.adminSearchRag)))