create-principles-disciple 1.100.0 → 1.102.0

package/console/dist/ui/pages/welcome/WelcomePage.js

@@ -0,0 +1,185 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { CircuitDiagram } from '../../components/onboarding/CircuitDiagram.js';
+import { DemoResultView } from '../../components/onboarding/DemoResultView.js';
+import { getOnboardingState, setOnboardingState } from '../../utils/onboarding-state.js';
+import { request } from '../../api.js';
+// Polling configuration for step 3 evidence detection (spec 6.5.2).
+const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+const POLL_INTERVAL_MS = 30 * 1000;
+// rc-1/rc-2/rc-4: validate the demo response shape before use.
+// The backend owns this shape, but parsed JSON is treated as unknown.
+function isDemoStage(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const name = Object.hasOwn(value, 'name') ? Reflect.get(value, 'name') : undefined;
+    const status = Object.hasOwn(value, 'status') ? Reflect.get(value, 'status') : undefined;
+    if (typeof name !== 'string')
+        return false;
+    return status === 'passed' || status === 'failed' || status === 'degraded' || status === 'skipped';
+}
+function parseDemoResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const v = value;
+    if (typeof v.simulated !== 'boolean')
+        return null;
+    if (typeof v.demo !== 'object' || v.demo === null)
+        return null;
+    const d = v.demo;
+    if (typeof d.status !== 'string')
+        return null;
+    const demo = { status: d.status };
+    if (typeof d.generatedAt === 'string')
+        demo.generatedAt = d.generatedAt;
+    if (typeof d.narrative === 'string')
+        demo.narrative = d.narrative;
+    if (typeof d.storyDescription === 'string')
+        demo.storyDescription = d.storyDescription;
+    if (typeof d.simulated === 'boolean')
+        demo.simulated = d.simulated;
+    if (Object.hasOwn(d, 'stages')) {
+        if (!Array.isArray(d.stages) || !d.stages.every(isDemoStage))
+            return null;
+        demo.stages = d.stages;
+    }
+    return { demo, simulated: v.simulated };
+}
+export function WelcomePage({ workspaceId }) {
+    const { t } = useTranslation();
+    const navigate = useNavigate();
+    const [step, setStep] = useState(1);
+    const [demoStatus, setDemoStatus] = useState('idle');
+    const [demoResult, setDemoResult] = useState(null);
+    const [demoError, setDemoError] = useState(null);
+    const [stateError, setStateError] = useState(null);
+    const [pollingActive, setPollingActive] = useState(false);
+    const [pollingStatus, setPollingStatus] = useState('idle');
+    const [pollingError, setPollingError] = useState(null);
+    // Refs for polling cleanup (spec 6.5.2 test case 3: unmount clears timers).
+    const pollingIntervalRef = useRef(null);
+    const pollingTimeoutRef = useRef(null);
+    // P2-2B: track consecutive polling errors; after 3, stop polling and surface
+    // the failure (rc-9: no silent fallback). Reset to 0 on any successful poll.
+    const errorCountRef = useRef(0);
+    // P2-3: baseline record count captured when polling starts, so we only
+    // trigger evidence-found on NEW evidence (not pre-existing records).
+    const baselineCountRef = useRef(0);
+    // If onboarding was already completed for this workspace, skip the wizard.
+    useEffect(() => {
+        const state = getOnboardingState(workspaceId);
+        if (state.completed) {
+            navigate('/focus', { replace: true });
+        }
+    }, [workspaceId, navigate]);
+    const completeOnboarding = useCallback((status) => {
+        if (!setOnboardingState(workspaceId, {
+            completed: true,
+            step: 3,
+            status,
+            completedAt: new Date().toISOString(),
+        })) {
+            setStateError(t('pages.welcome.stateSaveError'));
+            return;
+        }
+        navigate('/focus', { replace: true });
+    }, [workspaceId, navigate, t]);
+    const runDemo = useCallback(async () => {
+        setDemoStatus('loading');
+        setDemoError(null);
+        try {
+            const response = await request('/api/v1/onboarding/run-demo', { method: 'POST' }, parseDemoResponse);
+            if (!response.success) {
+                throw new Error(response.error);
+            }
+            setDemoResult(response.data.demo);
+            setDemoStatus('success');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Demo failed to start';
+            setDemoError(message);
+            setDemoStatus('error');
+        }
+    }, []);
+    const skipOnboarding = useCallback(() => {
+        completeOnboarding('skipped');
+    }, [completeOnboarding]);
+    // EP-05 (Loop State Freshness): each poll fetches fresh evidence.
+    const stopPolling = useCallback(() => {
+        setPollingActive(false);
+        if (pollingIntervalRef.current) {
+            clearInterval(pollingIntervalRef.current);
+            pollingIntervalRef.current = null;
+        }
+        if (pollingTimeoutRef.current) {
+            clearTimeout(pollingTimeoutRef.current);
+            pollingTimeoutRef.current = null;
+        }
+    }, []);
+    const startPolling = useCallback(() => {
+        setPollingActive(true);
+        setPollingStatus('polling');
+        setPollingError(null);
+        errorCountRef.current = 0;
+        pollingTimeoutRef.current = setTimeout(() => {
+            setPollingStatus('timeout');
+            stopPolling();
+        }, TWO_HOURS_MS);
+        // P2-3: capture baseline count on first poll, then only trigger
+        // evidence-found when count exceeds baseline (NEW evidence appeared).
+        let baselineCaptured = false;
+        const checkForEvidence = async () => {
+            try {
+                const response = await request('/api/v1/evidence-chain');
+                // P2-A: request() returns { success: false, error } on HTTP/network
+                // errors instead of throwing. Convert non-success into a thrown error
+                // so the catch block (error counter + retry UI) actually fires.
+                if (!response.success) {
+                    throw new Error(response.error || 'Failed to fetch evidence');
+                }
+                if (response.data) {
+                    const data = response.data;
+                    if (typeof data === 'object' && data !== null && Object.hasOwn(data, 'records')) {
+                        const records = data.records;
+                        if (Array.isArray(records)) {
+                            // P2-2B: a successful poll with valid data resets the error streak.
+                            errorCountRef.current = 0;
+                            if (!baselineCaptured) {
+                                // First poll: capture baseline count, do not trigger.
+                                baselineCountRef.current = records.length;
+                                baselineCaptured = true;
+                                return;
+                            }
+                            if (records.length > baselineCountRef.current) {
+                                setPollingStatus('evidence-found');
+                                stopPolling();
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // P2-2B (rc-9: no silent fallback) — surface the failure instead of
+                // swallowing it. After 3 consecutive errors, stop polling and show the
+                // error UI so the user can retry rather than waiting up to 2 hours.
+                errorCountRef.current += 1;
+                setPollingError(t('pages.welcome.step3.pollingError'));
+                if (errorCountRef.current >= 3) {
+                    setPollingStatus('error');
+                    stopPolling();
+                }
+            }
+        };
+        checkForEvidence();
+        pollingIntervalRef.current = setInterval(checkForEvidence, POLL_INTERVAL_MS);
+    }, [stopPolling, t]);
+    // Cleanup on unmount (spec 6.5.2 test case 3: no memory leak).
+    useEffect(() => {
+        return () => {
+            stopPolling();
+        };
+    }, [stopPolling]);
+    return (_jsxs("div", { className: "welcome-page", role: "main", children: [_jsxs("header", { className: "welcome-header", children: [_jsx("h1", { children: t('pages.welcome.title') }), _jsx("p", { className: "welcome-subtitle", children: t('pages.welcome.subtitle') }), _jsx("div", { className: "welcome-step-indicator", role: "progressbar", "aria-valuetext": t('pages.welcome.stepIndicator', { current: step, total: 3 }), children: [1, 2, 3].map((s) => (_jsx("span", { className: `step-dot ${s === step ? 'active' : ''} ${s < step ? 'completed' : ''}` }, s))) })] }), stateError && _jsx("p", { className: "polling-error", role: "alert", children: stateError }), step === 1 && (_jsxs("section", { className: "welcome-step welcome-step-1", "aria-labelledby": "step1-title", children: [_jsx("h2", { id: "step1-title", children: t('pages.welcome.step1.title') }), _jsx("p", { children: t('pages.welcome.step1.description') }), _jsx(CircuitDiagram, {}), _jsxs("div", { className: "welcome-actions", children: [_jsx("button", { className: "pd-btn pd-btn-brand", onClick: () => setStep(2), children: t('pages.welcome.step1.startButton') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: skipOnboarding, children: t('pages.welcome.step1.skipButton') })] })] })), step === 2 && (_jsxs("section", { className: "welcome-step welcome-step-2", "aria-labelledby": "step2-title", children: [_jsx("h2", { id: "step2-title", children: t('pages.welcome.step2.title') }), _jsx("p", { children: t('pages.welcome.step2.description') }), _jsx(DemoResultView, { result: demoResult, loading: demoStatus === 'loading', error: demoError }), _jsxs("div", { className: "welcome-actions", children: [demoStatus === 'idle' && (_jsx("button", { className: "pd-btn pd-btn-brand", onClick: runDemo, children: t('pages.welcome.step2.runDemoButton') })), (demoStatus === 'success' || demoStatus === 'error') && (_jsx("button", { className: "pd-btn pd-btn-alt", onClick: () => setStep(3), children: t('pages.welcome.step2.nextButton') }))] })] })), step === 3 && (_jsxs("section", { className: "welcome-step welcome-step-3", "aria-labelledby": "step3-title", children: [_jsx("h2", { id: "step3-title", children: t('pages.welcome.step3.title') }), _jsx("p", { children: t('pages.welcome.step3.description') }), _jsxs("div", { className: "example-prompt", role: "note", children: [_jsx("span", { className: "prompt-label", children: t('pages.welcome.step3.examplePrompt') }), _jsx("code", { className: "prompt-text", children: t('pages.welcome.step3.examplePromptText') })] }), pollingStatus === 'idle' && (_jsxs(_Fragment, { children: [_jsx("p", { className: "window-hint", children: t('pages.welcome.step3.windowHint') }), _jsxs("div", { className: "welcome-actions", children: [_jsx("button", { className: "pd-btn pd-btn-brand", onClick: () => { startPolling(); }, children: t('pages.welcome.step3.tryNowButton') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: () => completeOnboarding('demo'), children: t('pages.welcome.step3.goToFocusButton') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: skipOnboarding, children: t('pages.welcome.step3.skipButton') })] })] })), pollingStatus === 'polling' && (_jsxs("div", { className: "polling-active", role: "status", "aria-live": "polite", children: [_jsx("p", { children: t('pages.welcome.step3.pollingActive') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: () => { stopPolling(); completeOnboarding('demo'); }, children: t('pages.welcome.step3.stopPollingButton') })] })), pollingStatus === 'evidence-found' && (_jsxs("div", { className: "polling-success", role: "status", children: [_jsx("p", { children: t('pages.welcome.step3.evidenceFound') }), _jsx("button", { className: "pd-btn pd-btn-brand", onClick: () => completeOnboarding('evidence_found'), children: t('pages.welcome.step3.goToFocusButton') })] })), pollingStatus === 'timeout' && (_jsxs("div", { className: "polling-timeout", role: "status", children: [_jsx("p", { children: t('pages.welcome.step3.timeoutHint') }), _jsx("button", { className: "pd-btn pd-btn-brand", onClick: () => completeOnboarding('demo'), children: t('pages.welcome.step3.goToFocusButton') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: skipOnboarding, children: t('pages.welcome.step3.skipButton') })] })), pollingStatus === 'error' && (_jsxs("div", { className: "polling-error", role: "alert", children: [_jsx("p", { children: pollingError ?? t('pages.welcome.step3.pollingError') }), _jsxs("div", { className: "welcome-actions", children: [_jsx("button", { className: "pd-btn pd-btn-brand", onClick: () => { startPolling(); }, children: t('pages.welcome.step3.retryButton') }), _jsx("button", { className: "pd-btn pd-btn-alt", onClick: () => completeOnboarding('demo'), children: t('pages.welcome.step3.goToFocusButton') })] })] }))] }))] }));
+}

package/console/dist/ui/utils/__tests__/onboarding-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/console/dist/ui/utils/__tests__/onboarding-state.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+// Mock localStorage
+const localStorageMock = (() => {
+    let store = {};
+    return {
+        getItem: vi.fn((key) => store[key] ?? null),
+        setItem: vi.fn((key, value) => { store[key] = value; }),
+        removeItem: vi.fn((key) => { delete store[key]; }),
+        clear: vi.fn(() => { store = {}; }),
+    };
+})();
+Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock });
+import { getOnboardingState, setOnboardingState, resetOnboardingState, ONBOARDING_STORAGE_KEY_PREFIX } from '../onboarding-state.js';
+describe('Onboarding state with workspaceId dimension', () => {
+    beforeEach(() => {
+        localStorageMock.clear();
+        localStorageMock.getItem.mockClear();
+        localStorageMock.setItem.mockClear();
+        localStorageMock.removeItem.mockClear();
+    });
+    it('reports write and reset failures so callers cannot show false success', () => {
+        localStorageMock.setItem.mockImplementationOnce(() => { throw new Error('quota'); });
+        expect(setOnboardingState('ws-full', { completed: true, step: 3, status: 'demo' })).toBe(false);
+        localStorageMock.removeItem.mockImplementationOnce(() => { throw new Error('blocked'); });
+        expect(resetOnboardingState('ws-full')).toBe(false);
+    });
+    it('Given new workspace, When getOnboardingState called, Then returns default incomplete state', () => {
+        const state = getOnboardingState('ws-123');
+        expect(state.completed).toBe(false);
+        expect(state.step).toBe(0);
+        expect(state.status).toBe('pending');
+    });
+    it('Given onboarding completed, When setOnboardingState called with demo status, Then state persisted with workspaceId key', () => {
+        setOnboardingState('ws-123', { completed: true, step: 3, status: 'demo' });
+        const state = getOnboardingState('ws-123');
+        expect(state.completed).toBe(true);
+        expect(state.status).toBe('demo');
+        expect(state.step).toBe(3);
+    });
+    it('Given two workspaces, When state set for ws-A, Then ws-B state is independent (no cross-workspace leakage)', () => {
+        setOnboardingState('ws-A', { completed: true, step: 3, status: 'demo' });
+        const stateB = getOnboardingState('ws-B');
+        expect(stateB.completed).toBe(false);
+        expect(stateB.status).toBe('pending');
+    });
+    it('Given completed onboarding, When resetOnboardingState called, Then state returns to default', () => {
+        setOnboardingState('ws-123', { completed: true, step: 3, status: 'skipped' });
+        resetOnboardingState('ws-123');
+        const state = getOnboardingState('ws-123');
+        expect(state.completed).toBe(false);
+        expect(state.step).toBe(0);
+        expect(state.status).toBe('pending');
+    });
+    it('Given malformed localStorage data, When getOnboardingState called, Then returns safe default (rc-1 treat as unknown)', () => {
+        localStorageMock.getItem.mockReturnValueOnce('not-json');
+        const state = getOnboardingState('ws-broken');
+        expect(state.completed).toBe(false);
+        expect(state.status).toBe('pending');
+    });
+    it('Given non-string completedAt, When state is loaded, Then rejects the malformed contract', () => {
+        localStorageMock.getItem.mockReturnValueOnce(JSON.stringify({
+            completed: true, step: 3, status: 'evidence_found', completedAt: 123,
+        }));
+        expect(getOnboardingState('ws-invalid-date')).toEqual({
+            completed: false, step: 0, status: 'pending',
+        });
+    });
+    it('Given localStorage key prefix, Then key format is pd_onboarding_<workspaceId>', () => {
+        setOnboardingState('ws-123', { completed: true, step: 3, status: 'demo' });
+        expect(localStorageMock.setItem).toHaveBeenCalledWith(`${ONBOARDING_STORAGE_KEY_PREFIX}_ws-123`, expect.any(String));
+    });
+});

package/console/dist/ui/utils/agent-metadata.d.ts

@@ -42,6 +42,19 @@ export interface AgentMeta {
     /** MVP 状态说明（可选，仅 philosopher/rolloutReviewer 有） */
     mvpNoteZh?: string;
     mvpNoteEn?: string;
+    /** 操作入口（可选，仅侧链代理用于跳转管理页面） */
+    action?: ActionMeta;
+}
+/**
+ * 操作入口（可选，仅侧链代理用于跳转管理页面）
+ */
+export interface ActionMeta {
+    /** 链接文本（中） */
+    linkTextZh: string;
+    /** 链接文本（英） */
+    linkTextEn: string;
+    /** 路由路径 */
+    to: string;
 }
 export interface AgentGroupMeta {
     id: AgentGroup;

package/console/dist/ui/utils/agent-metadata.js

@@ -255,6 +255,11 @@ export const AGENT_METADATA = {
         techDetailZh: {},
         techDetailEn: {},
         isCore: true,
+        action: {
+            linkTextZh: '管理关键词',
+            linkTextEn: 'Manage Keywords',
+            to: '/control-center/signal-keywords?category=correction',
+        },
     },
     empathyObserver: {
         name: 'empathyObserver',
@@ -271,5 +276,26 @@ export const AGENT_METADATA = {
         techDetailZh: {},
         techDetailEn: {},
         isCore: true,
+        action: {
+            linkTextZh: '管理关键词',
+            linkTextEn: 'Manage Keywords',
+            to: '/control-center/signal-keywords?category=empathy',
+        },
+    },
+    signalCollector: {
+        name: 'signalCollector',
+        group: 'sidechain',
+        displayNameZh: '信号采集器',
+        displayNameEn: 'Signal Collector',
+        roleZh: '统一捕捉用户纠正与情绪反馈（合并原 correction + empathy）',
+        roleEn: 'Unified capture of user corrections and emotional feedback (merges former correction + empathy)',
+        detailZh: '以前有两套并行的用户反馈检测：correction（抓"你错了"）和 empathy（抓情绪挫败），词库重叠且各自维护。\n\n信号采集器把两者合并成一套：关键词快扫 + 本地 LLM 深度判断，按信号强度分流——明确纠错直接触发诊断，情绪推测走 GFI 累积。',
+        detailEn: 'Previously there were two parallel user-feedback detectors: correction (catching "you are wrong") and empathy (catching emotional frustration), with overlapping keyword stores maintained separately.\n\nThe Signal Collector merges them into one: keyword fast-scan + local LLM deep judgment, routed by signal strength — explicit corrections trigger diagnosis directly, emotional inference accumulates via GFI.',
+        impactLevel: 'amber',
+        impactZh: '退回纯关键词检测（高精度短语仍工作），LLM 深度判断关闭。歧义词和未命中场景召回率下降。',
+        impactEn: 'Falls back to keyword-only detection (high-precision phrases still work); LLM deep judgment disabled. Recall drops for ambiguous terms and missed cases.',
+        techDetailZh: {},
+        techDetailEn: {},
+        isCore: false,
     },
 };

package/console/dist/ui/utils/onboarding-state.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Onboarding state persistence with workspaceId dimension.
+ * Prevents cross-workspace state leakage (spec §6.3 改动 1).
+ * localStorage is the single source of truth (no cross-device sync — YAGNI).
+ */
+export interface OnboardingState {
+    completed: boolean;
+    step: number;
+    status: 'pending' | 'demo' | 'skipped' | 'evidence_found';
+    completedAt?: string;
+}
+export declare const ONBOARDING_STORAGE_KEY_PREFIX = "pd_onboarding";
+/**
+ * Get onboarding state for a specific workspace.
+ * Treats localStorage data as unknown (rc-1) — validates shape before use.
+ */
+export declare function getOnboardingState(workspaceId: string): OnboardingState;
+/**
+ * Set onboarding state for a specific workspace.
+ */
+export declare function setOnboardingState(workspaceId: string, state: OnboardingState): boolean;
+/**
+ * Reset onboarding state for a specific workspace (Settings page "reset" button).
+ */
+export declare function resetOnboardingState(workspaceId: string): boolean;

package/console/dist/ui/utils/onboarding-state.js

@@ -0,0 +1,77 @@
+/**
+ * Onboarding state persistence with workspaceId dimension.
+ * Prevents cross-workspace state leakage (spec §6.3 改动 1).
+ * localStorage is the single source of truth (no cross-device sync — YAGNI).
+ */
+const DEFAULT_STATE = {
+    completed: false,
+    step: 0,
+    status: 'pending',
+};
+export const ONBOARDING_STORAGE_KEY_PREFIX = 'pd_onboarding';
+function storageKey(workspaceId) {
+    return `${ONBOARDING_STORAGE_KEY_PREFIX}_${workspaceId}`;
+}
+/**
+ * Type guard for OnboardingState (rc-2: no `as` bypass).
+ */
+function isOnboardingState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const completed = Object.hasOwn(value, 'completed') ? Reflect.get(value, 'completed') : undefined;
+    const step = Object.hasOwn(value, 'step') ? Reflect.get(value, 'step') : undefined;
+    const status = Object.hasOwn(value, 'status') ? Reflect.get(value, 'status') : undefined;
+    const completedAt = Object.hasOwn(value, 'completedAt') ? Reflect.get(value, 'completedAt') : undefined;
+    return (typeof completed === 'boolean' &&
+        typeof step === 'number' &&
+        (status === 'pending' || status === 'demo' || status === 'skipped' || status === 'evidence_found') &&
+        (!Object.hasOwn(value, 'completedAt') || typeof completedAt === 'string'));
+}
+/**
+ * Get onboarding state for a specific workspace.
+ * Treats localStorage data as unknown (rc-1) — validates shape before use.
+ */
+export function getOnboardingState(workspaceId) {
+    try {
+        const raw = localStorage.getItem(storageKey(workspaceId));
+        if (!raw)
+            return DEFAULT_STATE;
+        // rc-1: treat parsed JSON as unknown, validate shape
+        const parsed = JSON.parse(raw);
+        if (!isOnboardingState(parsed))
+            return DEFAULT_STATE;
+        return parsed;
+    }
+    catch (err) {
+        // rc-9: surface the failure — don't silently swallow.
+        console.error('[onboarding-state] Failed to read onboarding state:', err);
+        return DEFAULT_STATE;
+    }
+}
+/**
+ * Set onboarding state for a specific workspace.
+ */
+export function setOnboardingState(workspaceId, state) {
+    try {
+        localStorage.setItem(storageKey(workspaceId), JSON.stringify(state));
+        return true;
+    }
+    catch (err) {
+        // rc-9: surface the failure — don't silently swallow.
+        console.error('[onboarding-state] Failed to save onboarding state:', err);
+        return false;
+    }
+}
+/**
+ * Reset onboarding state for a specific workspace (Settings page "reset" button).
+ */
+export function resetOnboardingState(workspaceId) {
+    try {
+        localStorage.removeItem(storageKey(workspaceId));
+        return true;
+    }
+    catch (err) {
+        console.error('[onboarding-state] Failed to reset onboarding state:', err);
+        return false;
+    }
+}

package/console/dist/ui/utils/signal-keywords-api.d.ts

@@ -0,0 +1,68 @@
+/**
+ * signal-keywords-api — 信号关键词 API 层
+ *
+ * 调用 OpenClaw 插件的信号关键词管理端点。
+ * 功能分阶段交付：
+ * - Phase 1：只读（fetch keywords + pending）
+ * - Phase 2：读写（update / admit / reject）
+ *
+ * 当前 Phase 1 实现；写方法为 stub，返回"未实现"错误。
+ *
+ * ERR entries:
+ * - rc-1: 所有响应经 validator 校验
+ * - rc-2: 无 `as` bypass
+ * - rc-9: 降级/失败路径含 reason
+ */
+import type { ApiResponse } from '../../types.js';
+import type { UnifiedKeywordStore, PendingTermStore, UpdateKeywordStoreRequest, AdmitPendingTermRequest, SignalKeyword, PendingSignalTerm } from './signal-keywords-types.js';
+/**
+ * 获取所有活跃关键词列表（SignalKeywordsPage 使用）
+ *
+ * 当前 Phase 1: 端点未实现，返回 stub 错误。
+ * Phase 2 需对接 /api/plugins/principles/signal-keywords 端点。
+ */
+export declare function listActiveSignalKeywords(_signal?: AbortSignal): Promise<ApiResponse<SignalKeyword[]>>;
+/**
+ * 获取待确认信号词列表（SignalKeywordsPage 使用）
+ *
+ * 当前 Phase 1: 端点未实现，返回 stub 错误。
+ * Phase 2 需对接 /api/plugins/principles/signal-keywords/pending 端点。
+ */
+export declare function listPendingSignalTerms(_signal?: AbortSignal): Promise<ApiResponse<PendingSignalTerm[]>>;
+/**
+ * 获取指定分类的信号词库
+ *
+ * @param category - 分类（correction | empathy）
+ * @param signal - 允许外部中止
+ */
+export declare function fetchKeywordStore(category: 'correction' | 'empathy', signal?: AbortSignal): Promise<ApiResponse<UnifiedKeywordStore>>;
+/**
+ * 获取 PendingTerm 候选池
+ *
+ * @param signal - 允许外部中止
+ */
+export declare function fetchPendingTerms(signal?: AbortSignal): Promise<ApiResponse<PendingTermStore>>;
+/**
+ * 更新信号词库
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export declare function updateKeywordStore(_req: UpdateKeywordStoreRequest, _signal?: AbortSignal): Promise<ApiResponse<{
+    version: number;
+}>>;
+/**
+ * 审批一个 PendingTerm（移入词库）
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export declare function admitPendingTerm(_req: AdmitPendingTermRequest, _signal?: AbortSignal): Promise<ApiResponse<{
+    version: number;
+}>>;
+/**
+ * 拒绝一个 PendingTerm（从候选池移除）
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export declare function rejectPendingTerm(_term: string, _signal?: AbortSignal): Promise<ApiResponse<{
+    version: number;
+}>>;

package/console/dist/ui/utils/signal-keywords-api.js

@@ -0,0 +1,121 @@
+/**
+ * signal-keywords-api — 信号关键词 API 层
+ *
+ * 调用 OpenClaw 插件的信号关键词管理端点。
+ * 功能分阶段交付：
+ * - Phase 1：只读（fetch keywords + pending）
+ * - Phase 2：读写（update / admit / reject）
+ *
+ * 当前 Phase 1 实现；写方法为 stub，返回"未实现"错误。
+ *
+ * ERR entries:
+ * - rc-1: 所有响应经 validator 校验
+ * - rc-2: 无 `as` bypass
+ * - rc-9: 降级/失败路径含 reason
+ */
+// ── 端点路径（当 plugin I/O 模块实现后启用） ──────────────────────────────────
+// const KEYWORDS_BASE = '/api/plugins/principles/signal-keywords';
+// ── SignalKeywordsPage 直接调用的列表函数 ──────────────────────────────────────
+/**
+ * 获取所有活跃关键词列表（SignalKeywordsPage 使用）
+ *
+ * 当前 Phase 1: 端点未实现，返回 stub 错误。
+ * Phase 2 需对接 /api/plugins/principles/signal-keywords 端点。
+ */
+export async function listActiveSignalKeywords(_signal) {
+    void _signal;
+    return {
+        success: false,
+        error: '信号关键词管理端点在当前版本中尚未实现（server-side plugin I/O 模块未部署）',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+/**
+ * 获取待确认信号词列表（SignalKeywordsPage 使用）
+ *
+ * 当前 Phase 1: 端点未实现，返回 stub 错误。
+ * Phase 2 需对接 /api/plugins/principles/signal-keywords/pending 端点。
+ */
+export async function listPendingSignalTerms(_signal) {
+    void _signal;
+    return {
+        success: false,
+        error: '信号关键词管理端点在当前版本中尚未实现（server-side plugin I/O 模块未部署）',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+// ── Phase 1 读取词库（category 分类读取） ──────────────────────────────────────
+/**
+ * 获取指定分类的信号词库
+ *
+ * @param category - 分类（correction | empathy）
+ * @param signal - 允许外部中止
+ */
+export async function fetchKeywordStore(category, signal) {
+    // Phase 1: 端点未实现，返回可识别的降级错误（rc-9）
+    // 见 Task 4 实施说明：server-side 端点不在本 PR 范围内
+    void category;
+    void signal;
+    return {
+        success: false,
+        error: '信号关键词管理端点在当前版本中尚未实现（server-side plugin I/O 模块未部署）',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+/**
+ * 获取 PendingTerm 候选池
+ *
+ * @param signal - 允许外部中止
+ */
+export async function fetchPendingTerms(signal) {
+    void signal;
+    return {
+        success: false,
+        error: '信号关键词管理端点在当前版本中尚未实现（server-side plugin I/O 模块未部署）',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+// ── 写操作（Phase 2 stubs） ───────────────────────────────────────────────────
+/**
+ * 更新信号词库
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export async function updateKeywordStore(_req, _signal) {
+    return {
+        success: false,
+        error: '写操作在当前版本中尚未实现',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+/**
+ * 审批一个 PendingTerm（移入词库）
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export async function admitPendingTerm(_req, _signal) {
+    return {
+        success: false,
+        error: '写操作在当前版本中尚未实现',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}
+/**
+ * 拒绝一个 PendingTerm（从候选池移除）
+ *
+ * Phase 2 实现，当前返回"未实现"。
+ */
+export async function rejectPendingTerm(_term, _signal) {
+    return {
+        success: false,
+        error: '写操作在当前版本中尚未实现',
+        reason: 'endpoint_not_implemented',
+        nextAction: '请等待后续版本更新后再使用此功能',
+    };
+}