Fix AI request time context

Rabithua · Rabithua · commit dc22d8a2e273 · 2026-07-07T22:43:48.000+08:00
diff --git a/server/route/v2/ai.ts b/server/route/v2/ai.ts
@@ -100,6 +100,7 @@ async function streamToolPlannedChatResponse(
     limit: body?.limit,
     excludeIds: body?.excludeIds,
     history: body?.history,
+    clientContext: body?.clientContext,
     enableThinking: body?.enableThinking === true,
     onPlanThinkingDelta: async (text) => {
       await writeSseEvent(stream, 'thinking', { phase: 'retrieval_planning', text });
@@ -366,12 +367,14 @@ aiRouter.post('/chat', authenticateJWT, bodyTypeCheck, async (c: HonoContext) =>
         limit: body?.limit,
         excludeIds: body?.excludeIds,
         history: body?.history,
+        clientContext: body?.clientContext,
       })
     : {
         answer: await createDirectSiteChat({
           userId: user.id,
           message,
           history: body?.history,
+          clientContext: body?.clientContext,
           enableThinking: body?.enableThinking === true,
         }),
         sources: [],
@@ -409,6 +412,7 @@ aiRouter.post('/agent/stream', authenticateJWT, bodyTypeCheck, async (c: HonoCon
           history: body?.history,
           state: body?.state,
           selectedContext: body?.selectedContext,
+          clientContext: body?.clientContext,
           debug: body?.debug,
           limit: body?.limit,
           previousPlan: body?.previousPlan,
@@ -455,6 +459,7 @@ aiRouter.post('/chat/stream', authenticateJWT, bodyTypeCheck, async (c: HonoCont
           userId: user.id,
           message,
           history: body?.history,
+          clientContext: body?.clientContext,
           enableThinking: body?.enableThinking === true,
           onReasoning: (text) => writeSseEvent(stream, 'thinking', { phase: 'answer', text }),
           onContent: (text) => writeSseEvent(stream, 'delta', { text }),
diff --git a/server/tests/aiRetrievalPlanner.test.ts b/server/tests/aiRetrievalPlanner.test.ts
@@ -133,6 +133,22 @@ describe('canonicalizeSearchRotesArgs', () => {
     expect(Date.parse(range?.from || '')).toBeLessThan(Date.parse(range?.to || ''));
   });
 
+  it('anchors relative dates to the client request date', () => {
+    const range = canonicalizeTimeRange({ timeExpression: '上月' }, undefined, {
+      nowIso: '2026-07-07T14:14:35.000Z',
+      localDate: '2026-07-07',
+      localDateTime: '2026-07-07T22:14:35+08:00',
+      timeZone: 'Asia/Shanghai',
+      utcOffsetMinutes: 480,
+    });
+
+    expect(range).toMatchObject({
+      from: '2026-06-01T00:00:00+08:00',
+      to: '2026-06-30T23:59:59+08:00',
+      label: '上个月',
+    });
+  });
+
   it('prefers structured timeRange DSL over free-text fields', () => {
     expect(
       canonicalizeTimeRange({
diff --git a/server/utils/ai/agent/runtime.ts b/server/utils/ai/agent/runtime.ts
@@ -10,6 +10,7 @@ import { getNativeRoteTools } from './tools';
 import {
   AgentToolCallingUnavailableError,
   DEFAULT_AGENT_POLICY,
+  type RoteAgentClientContext,
   type RoteAgentClientState,
   type RoteAgentContext,
   type RoteAgentEmitter,
@@ -28,6 +29,42 @@ function sourceKey(source: SemanticSearchResult): string {
   return `${source.sourceType}:${source.sourceId}`;
 }
 
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function sanitizeString(value: unknown, maxLength: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed.slice(0, maxLength) : undefined;
+}
+
+function sanitizeUtcOffsetMinutes(value: unknown): number | undefined {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return undefined;
+  const minutes = Math.trunc(numeric);
+  return minutes >= -14 * 60 && minutes <= 14 * 60 ? minutes : undefined;
+}
+
+function sanitizeClientContext(value: unknown): RoteAgentClientContext | null {
+  const raw = asRecord(value);
+  if (!Object.keys(raw).length) return null;
+
+  const context: RoteAgentClientContext = {
+    nowIso: sanitizeString(raw.nowIso, 64),
+    localDate: sanitizeString(raw.localDate, 32),
+    localDateTime: sanitizeString(raw.localDateTime, 64),
+    timeZone: sanitizeString(raw.timeZone, 80),
+    utcOffsetMinutes: sanitizeUtcOffsetMinutes(raw.utcOffsetMinutes),
+    locale: sanitizeString(raw.locale, 32),
+    calendar: sanitizeString(raw.calendar, 32),
+  };
+
+  return Object.values(context).some((item) => item !== undefined) ? context : null;
+}
+
 class SourceCollector {
   private sources: SemanticSearchResult[] = [];
   private indexByKey = new Map<string, number>();
@@ -68,6 +105,8 @@ function sanitizeAgentState(request: RoteAgentRequest): RoteAgentClientState {
     previousPlan: state.previousPlan || request.previousPlan || null,
     seenSourceIds,
     selectedContext: state.selectedContext || request.selectedContext || null,
+    clientContext:
+      sanitizeClientContext(state.clientContext) || sanitizeClientContext(request.clientContext),
     stateVersion: Number.isFinite(state.stateVersion) ? state.stateVersion : 1,
   };
 }
@@ -134,13 +173,51 @@ async function logChatUsage(userId: string, model: string, usage: any): Promise<
   });
 }
 
-function buildInitialMessages(request: RoteAgentRequest): ChatMessage[] {
+function buildRequestTimeContextMessage(state: RoteAgentClientState): ChatMessage {
+  const clientContext = state.clientContext;
+  const lines = [
+    '## Current request time context',
+    `Server now (UTC): ${new Date().toISOString()}`,
+  ];
+
+  if (clientContext) {
+    if (clientContext.nowIso) lines.push(`Client now (UTC): ${clientContext.nowIso}`);
+    if (clientContext.localDate) lines.push(`Client local date: ${clientContext.localDate}`);
+    if (clientContext.localDateTime) {
+      lines.push(`Client local date/time: ${clientContext.localDateTime}`);
+    }
+    if (clientContext.timeZone) lines.push(`Client time zone: ${clientContext.timeZone}`);
+    if (typeof clientContext.utcOffsetMinutes === 'number') {
+      lines.push(`Client UTC offset minutes: ${clientContext.utcOffsetMinutes}`);
+    }
+    if (clientContext.locale) lines.push(`Client locale: ${clientContext.locale}`);
+    if (clientContext.calendar) lines.push(`Client calendar: ${clientContext.calendar}`);
+  } else {
+    lines.push(
+      'Client time context was not supplied; use server now and Asia/Shanghai for Rote date ranges.'
+    );
+  }
+
+  lines.push(
+    'Resolve relative date phrases such as today, yesterday, this month, last month, 最近, 本月, and 上月 using this context.',
+    'When calling rote_search_notes for a relative date phrase, pass the phrase as timeExpression instead of inventing absolute from/to dates.',
+    'Use from/to only when the user explicitly provides absolute dates.'
+  );
+
+  return { role: 'system', content: lines.join('\n') };
+}
+
+function buildInitialMessages(
+  request: RoteAgentRequest,
+  state: RoteAgentClientState
+): ChatMessage[] {
   const mode = request.mode || 'chat';
   const messages: ChatMessage[] = [
     {
       role: 'system',
       content: buildRoteAgentSystemPrompt(mode),
     },
+    buildRequestTimeContextMessage(state),
   ];
 
   if (request.history?.length) {
@@ -210,7 +287,7 @@ export async function runRoteAgentStream(params: {
     getSources: () => sourceCollector.list(),
   };
 
-  const messages = buildInitialMessages(request);
+  const messages = buildInitialMessages(request, state);
   let toolCallCount = 0;
   let hasFinalAnswer = false;
 
diff --git a/server/utils/ai/agent/types.ts b/server/utils/ai/agent/types.ts
@@ -36,15 +36,27 @@ export type RoteAgentClientState = {
     selectedSourceIds?: string[];
     selectedTags?: string[];
   } | null;
+  clientContext?: RoteAgentClientContext | null;
   stateVersion?: number;
 };
 
+export type RoteAgentClientContext = {
+  nowIso?: string;
+  localDate?: string;
+  localDateTime?: string;
+  timeZone?: string;
+  utcOffsetMinutes?: number;
+  locale?: string;
+  calendar?: string;
+};
+
 export type RoteAgentRequest = {
   message: string;
   mode?: RoteAgentMode;
   history?: { role: 'user' | 'assistant'; content: string }[];
   state?: RoteAgentClientState | null;
   selectedContext?: RoteAgentClientState['selectedContext'];
+  clientContext?: RoteAgentClientContext | null;
   debug?: boolean;
   limit?: number;
   previousPlan?: PlannerAgentDto | null;
diff --git a/server/utils/ai/directChat.ts b/server/utils/ai/directChat.ts
@@ -6,12 +6,49 @@ import {
 } from './client';
 import { getStoredAiConfig } from '../dbMethods/ai';
 import { logAiTokenUsage } from '../dbMethods/aiToken';
+import type { RetrievalTimeContext } from './retrievalPlan';
 
 function buildMessages(
   message: string,
-  history?: Array<{ role: 'user' | 'assistant'; content: string }>
+  history?: Array<{ role: 'user' | 'assistant'; content: string }>,
+  clientContext?: RetrievalTimeContext | null
 ): ChatMessage[] {
-  return [...(Array.isArray(history) ? history.slice(-8) : []), { role: 'user', content: message }];
+  const messages: ChatMessage[] = [
+    {
+      role: 'system',
+      content: buildTimeContextMessage(clientContext),
+    },
+  ];
+  if (Array.isArray(history)) {
+    messages.push(...history.slice(-8));
+  }
+  messages.push({ role: 'user', content: message });
+  return messages;
+}
+
+function buildTimeContextMessage(clientContext?: RetrievalTimeContext | null): string {
+  const lines = [
+    'Use the current request time context for relative date phrases.',
+    `Server now (UTC): ${new Date().toISOString()}`,
+  ];
+
+  if (clientContext) {
+    if (clientContext.nowIso) lines.push(`Client now (UTC): ${clientContext.nowIso}`);
+    if (clientContext.localDate) lines.push(`Client local date: ${clientContext.localDate}`);
+    if (clientContext.localDateTime) {
+      lines.push(`Client local date/time: ${clientContext.localDateTime}`);
+    }
+    if (clientContext.timeZone) lines.push(`Client time zone: ${clientContext.timeZone}`);
+    if (typeof clientContext.utcOffsetMinutes === 'number') {
+      lines.push(`Client UTC offset minutes: ${clientContext.utcOffsetMinutes}`);
+    }
+  } else {
+    lines.push(
+      'Client time context was not supplied; use server now and Asia/Shanghai by default.'
+    );
+  }
+
+  return lines.join('\n');
 }
 
 async function logUsage(userId: string, model: string, usage: ChatCompletionUsage) {
@@ -29,12 +66,13 @@ export async function createDirectSiteChat(params: {
   userId: string;
   message: string;
   history?: Array<{ role: 'user' | 'assistant'; content: string }>;
+  clientContext?: RetrievalTimeContext | null;
   enableThinking?: boolean;
 }) {
   const config = await getStoredAiConfig();
   const result = await createChatCompletion(
     config.chat,
-    buildMessages(params.message, params.history),
+    buildMessages(params.message, params.history, params.clientContext),
     {
       enableThinking: params.enableThinking,
     }
@@ -47,6 +85,7 @@ export async function streamDirectSiteChat(params: {
   userId: string;
   message: string;
   history?: Array<{ role: 'user' | 'assistant'; content: string }>;
+  clientContext?: RetrievalTimeContext | null;
   enableThinking?: boolean;
   onReasoning: (text: string) => Promise<void>;
   onContent: (text: string) => Promise<void>;
@@ -56,7 +95,7 @@ export async function streamDirectSiteChat(params: {
   let usage: ChatCompletionUsage | undefined;
   for await (const part of createChatCompletionStreamParts(
     config.chat,
-    buildMessages(params.message, params.history),
+    buildMessages(params.message, params.history, params.clientContext),
     { enableThinking: params.enableThinking }
   )) {
     if (part.type === 'reasoning') await params.onReasoning(part.text);
diff --git a/server/utils/ai/retrievalPlan.ts b/server/utils/ai/retrievalPlan.ts
diff --git a/server/utils/dbMethods/ai.ts b/server/utils/dbMethods/ai.ts
