feat: 新增本地微信查询工具 API

docs/agent/api.md

@@ -112,3 +112,37 @@ curl -H "$AUTH" "$BASE/chatlog?talker=技术交流群&time=2026-08-07"
 ## 与 MCP 的关系
 
 当前实现没有把 `6131` 暴露为 MCP Server。需要在 Agent 中使用时，请安装随应用提供的 Reader Skill，并让 Skill 通过普通 HTTP 请求调用本 API。
+
+## LLM-friendly Query Tool API
+
+这些端点提供稳定的结构化 Query primitive，不接收自然语言问题，也不会调用 AI。它们与现有 API 共用端口、Bearer Token、loopback 和 CORS 安全策略。
+
+```bash
+BASE="http://127.0.0.1:6131/api/v1"
+AUTH="Authorization: Bearer ${TRACEMEMO_API_TOKEN:-$WECHATEXPLORER_API_TOKEN}"
+
+# 能力目录
+curl -H "$AUTH" "$BASE/query/capabilities"
+
+# BOBO 的第一条真实互动
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/messages" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"all"},"direction":"any","order":"asc","limit":1,"excludeSystem":true}'
+
+# 上个月 BOBO 发来的文件
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/messages" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"previous_month"},"direction":"from_target","messageTypes":["file"],"order":"desc","limit":1}'
+
+# 受限语义关键词检索（最多 4 个 variants）
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/search" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"all"},"query":"答应之后给我或者帮我完成某件事情","variants":["我给你","我发你","弄好给你"],"limit":20}'
+
+# 按会话和时间范围提取可供总结的证据
+curl -X POST -H "$AUTH" -H 'Content-Type: application/json' "$BASE/query/conversation-overview" \
+  -d '{"target":{"query":"BOBO"},"timeRange":{"kind":"previous_month"}}'
+```
+
+`query/messages` 的 `messageRef` 是服务端生成的不透明引用，可直接传给 `query/message-context` 获取前后文；不要自行构造 wxid、md5 或数据库路径。
+
+每条消息都会返回 `messageType`（`text`、`image`、`voice`、`video`、`file`、`link`、`sticker`、`system` 或 `other`）。非文本消息不会伪造 `text`；可识别的图片、视频、贴纸和文件会返回不含密钥或本地路径的 `attachment` 元数据。
+
+`conversation-overview` 同时返回 `sourceCoverage` 与 `selection`：前者描述时间范围内源消息是否完整及 `sourceMessageCount`，后者描述从源消息中选出的 Evidence 数量及是否抽样。`evidence` 最终按 `timestamp` 升序返回，`messageRef` 是唯一推荐的消息引用。

src/main/http-server.ts

@@ -26,6 +26,7 @@ import { agentHubService } from './services/agent-hub-service'
 import { safeError, safeLog, safeWarn } from './safe-log'
 import { apiTokenStore } from './api-token-store'
 import { HttpMediaError, readImageMedia, type HttpImageResult } from './http-media-service'
+import { LocalQueryApiService } from './services/local-query-api-service'
 
 export const DEFAULT_HTTP_HOST = '127.0.0.1'
 export const DEFAULT_HTTP_PORT = 6131
@@ -51,6 +52,12 @@ export interface HttpServerOptions {
   scheduledReportContactsProvider?: ScheduledReportApiDependencies['listContacts']
   scheduledReportDatabaseReadyProvider?: ScheduledReportApiDependencies['isDatabaseReady']
   scheduledReportPlatform?: NodeJS.Platform
+  queryApiService?: LocalQueryApiService
+}
+
+let configuredQueryApiService: LocalQueryApiService | undefined
+export function setLocalQueryApiService(service: LocalQueryApiService | undefined): void {
+  configuredQueryApiService = service
 }
 
 type RouteHandler = (ctx: RouteContext) => void | Promise<void>
@@ -542,6 +549,45 @@ function createScheduledReportRoute(
 }
 
 const MEDIA_ROUTE_PREFIX = '/api/v1/media/'
+const QUERY_ROUTE_PREFIX = '/api/v1/query/'
+
+function queryStatusCode(status: string): number {
+  if (status === 'completed') return 200
+  if (status === 'contact_not_found') return 404
+  if (status === 'ambiguous_contact') return 409
+  if (status === 'knowledge_unavailable') return 503
+  if (status === 'retrieval_incomplete') return 206
+  return 400
+}
+
+function createQueryRoute(api: LocalQueryApiService): RouteHandler | undefined {
+  return async ({ req, res, body }) => {
+    const pathname = new URL(req.url || '/', 'http://localhost').pathname
+    if (pathname === '/api/v1/query/capabilities') {
+      if (req.method !== 'GET') return sendError(res, 405, '需要 GET 请求')
+      return sendJson(res, 200, api.capabilities())
+    }
+    if (req.method !== 'POST') return sendError(res, 405, '需要 POST 请求')
+    let payload: any
+    try { payload = JSON.parse(typeof body === 'string' ? body : '') } catch { return sendError(res, 400, 'invalid_request') }
+    if (!payload || typeof payload !== 'object') return sendError(res, 400, 'invalid_request')
+    try {
+      const result = pathname === '/api/v1/query/messages'
+        ? await api.messages(payload)
+        : pathname === '/api/v1/query/search'
+          ? await api.search(payload)
+          : pathname === '/api/v1/query/message-context'
+            ? await api.context(payload)
+            : pathname === '/api/v1/query/conversation-overview'
+              ? await api.overview(payload)
+              : undefined
+      if (!result) return sendError(res, 404, `端点不存在: ${pathname}`)
+      return sendJson(res, queryStatusCode(result.status), result)
+    } catch (error) {
+      return sendError(res, 400, error instanceof Error ? error.message : 'invalid_request')
+    }
+  }
+}
 
 function createMediaRoute(
   mediaProvider: (messageId: string) => Promise<HttpImageResult>
@@ -599,6 +645,7 @@ export function startHttpServer(
   const tokenProvider = options.tokenProvider || (() => apiTokenStore.getTokenForAuthentication())
   const mediaProvider = options.mediaProvider || readImageMedia
   const scheduledReportApi = createScheduledReportApi(options)
+  const queryApi = options.queryApiService || configuredQueryApiService || new LocalQueryApiService()
   return new Promise((resolve, reject) => {
     const server: Server = http.createServer(async (req, res) => {
       try {
@@ -613,6 +660,7 @@ export function startHttpServer(
         const handler =
           routes[url.pathname] ||
           createScheduledReportRoute(url.pathname, scheduledReportApi) ||
+          (url.pathname.startsWith(QUERY_ROUTE_PREFIX) ? createQueryRoute(queryApi) : undefined) ||
           (url.pathname.startsWith(MEDIA_ROUTE_PREFIX)
             ? createMediaRoute(mediaProvider)
             : undefined)

src/main/index.ts

@@ -74,7 +74,7 @@ import type {
 import { KeyServiceMac } from './key-service-mac'
 import { KeyService as KeyServiceWin } from './key-service-win'
 import * as chat from './services/chat-service'
-import { apiServer } from './http-server'
+import { apiServer, setLocalQueryApiService } from './http-server'
 import { skillResourceService } from './services/skill-resource-service'
 import { buildLocalApiCurlCommand, testLocalApiRequest } from './services/local-api-test-service'
 import { isWechatRunning } from './services/wechat-process-status'
@@ -163,6 +163,7 @@ import {
   WINDOWS_VC_RUNTIME_ERROR_MESSAGE
 } from '../shared/windows-runtime'
 import { KnowledgeSearchService } from './knowledge/knowledge-search-service'
+import { LocalQueryApiService } from './services/local-query-api-service'
 import { AiSearchPipelineService } from './services/ai-search-pipeline-service'
 import { runLegacySafeStorageHelper } from './legacy-safe-storage-helper'
 import { runFirstLaunchMigration } from './app-data-migration'
@@ -182,6 +183,7 @@ let voiceService: VoiceService | null = null
 let voiceRecognition: VoiceRecognitionUseCase | null = null
 let voiceBatchService: VoiceBatchService | null = null
 let knowledgeSearchService: KnowledgeSearchService | null = null
+let localQueryApiService: LocalQueryApiService | null = null
 let aiSearchPipelineService: AiSearchPipelineService | null = null
 let imageDecryptService: ImageDecryptService | null = null
 let stickerService: StickerService | null = null
@@ -614,6 +616,8 @@ app.whenReady().then(async () => {
     knowledgeSearchService?.indexVoiceTranscript(update)
   )
   aiSearchPipelineService = new AiSearchPipelineService(knowledgeSearchService, aiProviderService)
+  localQueryApiService = new LocalQueryApiService(knowledgeSearchService)
+  setLocalQueryApiService(localQueryApiService)
   knowledgeSearchService.onStatusChange((status) => {
     for (const window of BrowserWindow.getAllWindows()) {
       if (!window.isDestroyed()) window.webContents.send('knowledge:status', status)

src/main/services/local-query-api-service.ts

@@ -0,0 +1,112 @@
+import { listContactsAsync, listMessagesAsync, isReady, type FormattedContact, type FormattedMessage } from './chat-service'
+import { resolveContact } from './contact-resolution-service'
+import type { KnowledgeSearchService } from '../knowledge/knowledge-search-service'
+import { inferAiSearchTimeRange } from '../../shared/ai-search'
+import type { QueryCapabilitiesResponse, QueryMessage, QueryMessageType, QueryTimeRange, ResolvedTimeRange, QueryMessagesRequest, SearchMessagesRequest, MessageContextRequest, ConversationOverviewRequest } from '../../shared/local-query-api'
+
+const LIMIT_MAX = 200
+const CONTEXT_MAX = 50
+const kinds: QueryMessageType[] = ['text', 'image', 'voice', 'video', 'file', 'link', 'sticker', 'system', 'other']
+
+function kindOf(message: FormattedMessage): QueryMessageType {
+  if (message.contentData?.type === 'system') return 'system'
+  if (message.exportMediaType) return message.exportMediaType
+  if (message.type === '语音' || message.voiceTranscript) return 'voice'
+  if (message.contentData?.type === 'image') return 'image'
+  if (message.contentData?.type === 'video') return 'video'
+  if (message.contentData?.type === 'sticker') return 'sticker'
+  if (message.contentData?.type === 'share') return message.contentData.typeVal === '6' ? 'file' : 'link'
+  if (message.contentData?.type === 'miniProgram') return 'link'
+  if (message.type === '文件') return 'file'
+  if (message.content?.trim()) return 'text'
+  return 'other'
+}
+function toRef(conversationId: string, messageId: string): string {
+  return Buffer.from(JSON.stringify({ c: conversationId, m: messageId }), 'utf8').toString('base64url')
+}
+function fromRef(value: string): { c: string; m: string } | null {
+  try {
+    const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'))
+    return typeof parsed?.c === 'string' && typeof parsed?.m === 'string' ? parsed : null
+  } catch { return null }
+}
+function contactView(contact: FormattedContact) { return { displayName: contact.m_nsNickName || contact.m_nsUsrName, type: contact.type } as const }
+function resolvedTimeRange(input: QueryTimeRange, now = new Date()): ResolvedTimeRange {
+  if (input.kind === 'absolute') {
+    if ((input.startTime !== undefined && !Number.isFinite(input.startTime)) || (input.endTime !== undefined && !Number.isFinite(input.endTime))) throw new Error('时间范围无效')
+    if (input.startTime !== undefined && input.endTime !== undefined && input.endTime < input.startTime) throw new Error('时间范围无效')
+    return { ...input, label: '指定时间范围' }
+  }
+  const map: Record<string, Parameters<typeof inferAiSearchTimeRange>[1]> = { all: 'all', today: 'today', yesterday: 'all', this_week: 'all', last_7_days: '7d', this_month: 'all', previous_month: 'all', this_year: 'all', previous_year: 'all' }
+  const phrase: Record<string, string> = { today: '今天', yesterday: '昨天', this_week: '本周', last_7_days: '近 7 天', this_month: '本月', previous_month: '上个月', this_year: '今年', previous_year: '去年', all: '' }
+  const range = inferAiSearchTimeRange(phrase[input.kind], map[input.kind], now)
+  return { kind: input.kind, startTime: range.startTime, endTime: range.endTime, label: range.label }
+}
+function toQueryMessage(conversationId: string, message: FormattedMessage, target: FormattedContact): QueryMessage {
+  const kind = kindOf(message)
+  const content = message.contentData
+  const attachment =
+    kind === 'image' && content?.type === 'image'
+      ? { kind: 'image' as const }
+      : kind === 'video' && content?.type === 'video'
+        ? { kind: 'video' as const, sizeBytes: content.byteLength }
+        : kind === 'sticker' && content?.type === 'sticker'
+          ? { kind: 'sticker' as const, url: content.url || content.thumbUrl }
+          : kind === 'file'
+            ? { kind: 'file' as const, name: message.exportMediaName || (content?.type === 'share' ? content.title : undefined), url: content?.type === 'share' ? content.url : undefined }
+            : undefined
+  const text = message.content?.trim() || message.voiceTranscript?.trim() || undefined
+  return { messageRef: toRef(conversationId, message.id), timestamp: (message.createTime || 0) * 1000, datetime: message.datetime, sender: message.isSender ? '我' : (message.name || target.m_nsNickName), direction: message.isSender ? 'to_target' : 'from_target', messageType: kind, sourceKind: kind, ...(attachment ? { attachment } : {}), ...(text ? { text } : {}) }
+}
+
+export class LocalQueryApiService {
+  constructor(private readonly knowledge?: KnowledgeSearchService, private readonly nowProvider: () => Date = () => new Date()) {}
+  capabilities(): QueryCapabilitiesResponse {
+    return { version: 1, tools: { query_messages: { operation: '读取指定联系人的确定性消息', directions: ['any', 'from_target', 'to_target'], messageTypes: kinds, timeRanges: ['all', 'today', 'yesterday', 'this_week', 'last_7_days', 'this_month', 'previous_month', 'this_year', 'previous_year', 'absolute'], limitMax: LIMIT_MAX }, search_messages: { operation: '受限 Knowledge 关键词检索', timeRanges: ['all', 'today', 'yesterday', 'this_week', 'last_7_days', 'this_month', 'previous_month', 'this_year', 'previous_year', 'absolute'], limitMax: LIMIT_MAX }, message_context: { operation: '读取消息前后文', timeRanges: ['all'], limitMax: CONTEXT_MAX }, conversation_overview: { operation: '按会话时间片提取概览证据', timeRanges: ['all', 'today', 'yesterday', 'this_week', 'last_7_days', 'this_month', 'previous_month', 'this_year', 'previous_year', 'absolute'], limitMax: LIMIT_MAX } } }
+  }
+  private async resolve(target: { query: string }) {
+    const contacts = await listContactsAsync()
+    const result = resolveContact(target.query, contacts)
+    return { contacts, result }
+  }
+  async messages(request: QueryMessagesRequest) {
+    if (!request?.target?.query?.trim() || !request.timeRange || !['any', 'from_target', 'to_target'].includes(request.direction || 'any') || (request.messageTypes || []).some((type) => !kinds.includes(type))) return { status: 'invalid_request' as const }
+    if (!isReady()) return { status: 'knowledge_unavailable' as const }
+    const { contacts, result } = await this.resolve(request.target)
+    if (!result.matched || !result.conversationId) return { status: result.ambiguous ? 'ambiguous_contact' as const : 'contact_not_found' as const, candidates: result.candidates.map((candidate) => ({ displayName: candidate.displayName, type: contacts.find((c) => c.md5 === candidate.conversationId)?.type || 'user' })) }
+    const contact = contacts.find((c) => c.md5 === result.conversationId)!; if (contact.type === 'group' && request.direction && request.direction !== 'any') return { status: 'unsupported_query' as const }; const range = resolvedTimeRange(request.timeRange, this.nowProvider())
+    const raw = await listMessagesAsync(contact.md5, range.startTime, range.endTime)
+    const direction = request.direction || 'any'; const allowed = new Set(request.messageTypes || kinds)
+    const filtered = raw.filter((message) => !(request.excludeSystem !== false && kindOf(message) === 'system')).filter((message) => allowed.has(kindOf(message))).filter((message) => direction === 'any' || (direction === 'to_target' ? message.isSender : !message.isSender)).sort((a, b) => ((a.createTime || 0) - (b.createTime || 0)) * ((request.order || 'asc') === 'asc' ? 1 : -1)).slice(0, Math.min(LIMIT_MAX, Math.max(1, request.limit || 20)))
+    return { status: 'completed' as const, target: contactView(contact), query: { direction, messageTypes: request.messageTypes || [], order: request.order || 'asc', limit: Math.min(LIMIT_MAX, Math.max(1, request.limit || 20)), excludeSystem: request.excludeSystem !== false, resolvedTimeRange: range }, coverage: { state: 'complete' as const }, returnedCount: filtered.length, messages: filtered.map((message) => toQueryMessage(contact.md5, message, contact)) }
+  }
+  async search(request: SearchMessagesRequest) {
+    if (!request?.target?.query?.trim() || !request.timeRange || typeof request.query !== 'string' || !request.query.trim() || (request.variants || []).some((value) => typeof value !== 'string')) return { status: 'invalid_request' as const }
+    const { contacts, result } = await this.resolve(request.target)
+    if (!result.matched || !result.conversationId) return { status: result.ambiguous ? 'ambiguous_contact' as const : 'contact_not_found' as const, candidates: result.candidates.map((candidate) => ({ displayName: candidate.displayName, type: contacts.find((c) => c.md5 === candidate.conversationId)?.type || 'user' })) }
+    if (!this.knowledge) return { status: 'knowledge_unavailable' as const }
+    const contact = contacts.find((c) => c.md5 === result.conversationId)!; const range = resolvedTimeRange(request.timeRange, this.nowProvider()); const probes = [request.query, ...(request.variants || [])]
+    if (probes.length > 5) return { status: 'invalid_request' as const }
+    const all = new Map<string, any>(); let coverage: 'complete' | 'partial' | 'unknown' = 'unknown'
+    for (const probe of probes) { const found = await this.knowledge.search({ text: probe, terms: [probe], conversationIds: [contact.md5], startTime: range.startTime, endTime: range.endTime, limit: Math.min(LIMIT_MAX, Math.max(1, request.limit || 20)) }); coverage = found.state === 'ready' ? 'complete' : found.evidence.length ? 'partial' : 'unknown'; for (const item of found.evidence) all.set(`${item.conversationId}:${item.messageId}`, { messageRef: toRef(item.conversationId, item.messageId), messageId: item.messageId, timestamp: item.timestamp, sender: item.sender, sourceKind: item.sourceKind, text: item.text }) }
+    return { status: 'completed' as const, target: contactView(contact), resolvedTimeRange: range, coverage: { state: coverage }, probeCount: probes.length, evidenceCount: all.size, evidence: Array.from(all.values()).map(({ messageId: _messageId, ...item }) => item).slice(0, request.limit || 20) }
+  }
+  async context(request: MessageContextRequest) {
+    const ref = fromRef(request.messageRef); if (!ref) return { status: 'invalid_request' as const }
+    const before = Math.min(CONTEXT_MAX, Math.max(0, request.before ?? 10)); const after = Math.min(CONTEXT_MAX, Math.max(0, request.after ?? 10)); const messages = await listMessagesAsync(ref.c); const index = messages.findIndex((message) => message.id === ref.m); if (index < 0) return { status: 'contact_not_found' as const }
+    const contact = (await listContactsAsync()).find((item) => item.md5 === ref.c); if (!contact) return { status: 'contact_not_found' as const }; const map = (message: FormattedMessage) => toQueryMessage(ref.c, message, contact)
+    return { status: 'completed' as const, anchor: map(messages[index]), before: messages.slice(Math.max(0, index - before), index).map(map), after: messages.slice(index + 1, index + 1 + after).map(map) }
+  }
+  async overview(request: ConversationOverviewRequest) {
+    if (!request?.target?.query?.trim() || !request.timeRange) return { status: 'invalid_request' as const }
+    const { contacts, result } = await this.resolve(request.target); if (!result.matched || !result.conversationId) return { status: result.ambiguous ? 'ambiguous_contact' as const : 'contact_not_found' as const, candidates: result.candidates.map((candidate) => ({ displayName: candidate.displayName, type: contacts.find((c) => c.md5 === candidate.conversationId)?.type || 'user' })) }; if (!this.knowledge) return { status: 'knowledge_unavailable' as const }
+    const contact = contacts.find((c) => c.md5 === result.conversationId)!; const range = resolvedTimeRange(request.timeRange, this.nowProvider()); const found = await this.knowledge.search({ text: '', terms: [], conversationIds: [contact.md5], startTime: range.startTime, endTime: range.endTime, limit: LIMIT_MAX }); const retrieval = found.conversationRetrieval
+    const sourceMessageCount = retrieval?.totalMessages || 0
+    const evidence = found.evidence
+      .map((item, index) => ({ messageRef: toRef(item.conversationId, item.messageId), timestamp: item.timestamp, sender: item.sender, sourceKind: item.sourceKind, text: item.text, index }))
+      .sort((left, right) => left.timestamp - right.timestamp || left.index - right.index)
+      .map(({ index: _index, ...item }) => item)
+    const sourceState = retrieval?.complete ? 'complete' as const : 'partial' as const
+    return { status: found.state === 'ready' ? 'completed' as const : 'retrieval_incomplete' as const, target: contactView(contact), resolvedTimeRange: range, coverage: { state: sourceState }, sourceMessageCount, evidenceCount: evidence.length, sourceCoverage: { state: sourceState, sourceMessageCount }, selection: { mode: 'temporal_coverage' as const, selectedEvidenceCount: evidence.length, sampled: evidence.length < sourceMessageCount }, voiceCoverage: found.voiceCoverage, evidence }
+  }
+}

src/shared/local-query-api.ts

@@ -0,0 +1,95 @@
+import type { KnowledgeEvidence, KnowledgeVoiceCoverage } from './knowledge'
+
+export type QueryDirection = 'any' | 'from_target' | 'to_target'
+export type QueryOrder = 'asc' | 'desc'
+export type QueryMessageType =
+  | 'text'
+  | 'image'
+  | 'voice'
+  | 'video'
+  | 'file'
+  | 'link'
+  | 'sticker'
+  | 'system'
+  | 'other'
+export type QueryTimeRange =
+  | { kind: 'all' | 'today' | 'yesterday' | 'this_week' | 'last_7_days' | 'this_month' | 'previous_month' | 'this_year' | 'previous_year' }
+  | { kind: 'absolute'; startTime?: number; endTime?: number }
+export interface QueryTarget { query: string }
+export interface ResolvedTimeRange { kind: QueryTimeRange['kind']; startTime?: number; endTime?: number; label: string }
+export interface QueryMessagesRequest {
+  target: QueryTarget
+  timeRange: QueryTimeRange
+  direction?: QueryDirection
+  messageTypes?: QueryMessageType[]
+  order?: QueryOrder
+  limit?: number
+  excludeSystem?: boolean
+}
+export interface QueryMessage {
+  messageRef: string
+  timestamp: number
+  datetime: string
+  sender: string
+  direction: 'from_target' | 'to_target'
+  messageType: QueryMessageType
+  sourceKind: QueryMessageType
+  text?: string
+  attachment?: {
+    kind: Exclude<QueryMessageType, 'text' | 'voice' | 'system' | 'other' | 'link'>
+    name?: string
+    url?: string
+    sizeBytes?: number
+  }
+}
+export interface QueryMessagesResponse {
+  status: string
+  target?: { displayName: string; type: 'user' | 'group' }
+  query?: Omit<QueryMessagesRequest, 'target' | 'timeRange'> & { resolvedTimeRange: ResolvedTimeRange }
+  coverage?: { state: 'complete' | 'partial' | 'unknown' }
+  returnedCount?: number
+  messages?: QueryMessage[]
+  candidates?: Array<{ displayName: string; type: 'user' | 'group' }>
+}
+export interface SearchMessagesRequest {
+  target: QueryTarget
+  timeRange: QueryTimeRange
+  query: string
+  variants?: string[]
+  limit?: number
+}
+export interface SearchMessagesResponse {
+  status: string
+  target?: { displayName: string; type: 'user' | 'group' }
+  resolvedTimeRange?: ResolvedTimeRange
+  coverage?: { state: 'complete' | 'partial' | 'unknown' }
+  probeCount?: number
+  evidenceCount?: number
+  evidence?: Array<Pick<KnowledgeEvidence, 'timestamp' | 'sender' | 'sourceKind' | 'text'> & { messageRef: string }>
+  candidates?: Array<{ displayName: string; type: 'user' | 'group' }>
+}
+export interface MessageContextRequest { messageRef: string; before?: number; after?: number }
+export interface MessageContextResponse {
+  status: string
+  anchor?: QueryMessage
+  before?: QueryMessage[]
+  after?: QueryMessage[]
+}
+export interface ConversationOverviewRequest { target: QueryTarget; timeRange: QueryTimeRange }
+export interface ConversationOverviewResponse {
+  status: string
+  target?: { displayName: string; type: 'user' | 'group' }
+  resolvedTimeRange?: ResolvedTimeRange
+  coverage?: { state: 'complete' | 'partial' | 'unknown' }
+  sourceMessageCount?: number
+  evidenceCount?: number
+  sourceCoverage?: { state: 'complete' | 'partial' | 'unknown'; sourceMessageCount: number }
+  selection?: { mode: 'temporal_coverage'; selectedEvidenceCount: number; sampled: boolean }
+  voiceCoverage?: KnowledgeVoiceCoverage
+  evidence?: Array<Pick<KnowledgeEvidence, 'timestamp' | 'sender' | 'sourceKind' | 'text'> & { messageRef: string }>
+  candidates?: Array<{ displayName: string; type: 'user' | 'group' }>
+}
+export interface QueryCapabilitiesResponse {
+  version: 1
+  tools: Record<string, { operation: string; directions?: QueryDirection[]; messageTypes?: QueryMessageType[]; timeRanges: QueryTimeRange['kind'][]; limitMax?: number }>
+}

tests/integration/local-api-auth.test.ts

@@ -127,6 +127,15 @@ describe('Local API authentication', () => {
     await expect(response.json()).resolves.toMatchObject({ count: 1 })
   })
 
+  it('exposes the query capability catalog only with the existing bearer token', async () => {
+    const handle = await startFixtureServer()
+    const path = `${baseUrl(handle)}/api/v1/query/capabilities`
+    expect((await fetch(path)).status).toBe(401)
+    const response = await fetch(path, { headers: { Authorization: `Bearer ${VALID_TOKEN}` } })
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({ version: 1, tools: { query_messages: { limitMax: 200 } } })
+  })
+
   it.each([
     ['GET', '/api/v1/current_time'],
     ['GET', '/api/v1/contact'],
@@ -139,7 +148,9 @@ describe('Local API authentication', () => {
     ['POST', '/api/v1/report'],
     ['GET', '/api/v1/agent/status'],
     ['POST', '/api/v1/agent/group-report'],
-    ['POST', '/api/v1/agent/send']
+    ['POST', '/api/v1/agent/send'],
+    ['GET', '/api/v1/query/capabilities'],
+    ['POST', '/api/v1/query/messages']
   ])('protects every non-health route: %s %s', async (method, pathname) => {
     const handle = await startFixtureServer()
     const response = await fetch(`${baseUrl(handle)}${pathname}`, {

tests/unit/local-query-api-service.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+
+const fixture = vi.hoisted(() => ({
+  contacts: [
+    { m_nsUsrName: 'wxid-bobo', m_nsNickName: 'BOBO', md5: 'md5-bobo', type: 'user' as const },
+    { m_nsUsrName: 'wxid-bobo-2', m_nsNickName: 'BOBO', md5: 'md5-bobo-2', type: 'user' as const }
+  ],
+  messages: [
+    { id: 'm1', from: 'user', type: '图片', datetime: '2026/8/2 10:00:00', content: '', contentData: { type: 'image', md5: 'image-md5' }, isSender: false, name: 'BOBO', createTime: Math.floor(new Date('2026-08-02T10:00:00+08:00').getTime() / 1000) },
+    { id: 'm2', from: 'assistant', type: '文件', datetime: '2026/8/3 10:00:00', content: '', isSender: true, exportMediaType: 'file' as const, exportMediaName: 'a.pdf', createTime: Math.floor(new Date('2026-08-03T10:00:00+08:00').getTime() / 1000) }
+  ]
+}))
+vi.mock('../../src/main/services/chat-service', () => ({
+  isReady: () => true,
+  listContactsAsync: vi.fn(async () => fixture.contacts),
+  listMessagesAsync: vi.fn(async () => fixture.messages)
+}))
+
+import { LocalQueryApiService } from '../../src/main/services/local-query-api-service'
+
+describe('LocalQueryApiService', () => {
+  const knowledge = { search: vi.fn(async () => ({ state: 'ready', evidence: [{ conversationId: 'md5-bobo', messageId: 'm1', timestamp: 1, sender: 'BOBO', sourceKind: 'text', text: '你好' }], conversationRetrieval: { totalMessages: 2, chunkCount: 1, complete: true }, voiceCoverage: undefined })) } as any
+  let service: LocalQueryApiService
+  beforeEach(() => { vi.clearAllMocks(); if (!fixture.contacts.some((contact) => contact.md5 === 'md5-bobo-2')) fixture.contacts.push({ m_nsUsrName: 'wxid-bobo-2', m_nsNickName: 'BOBO', md5: 'md5-bobo-2', type: 'user' }); service = new LocalQueryApiService(knowledge, () => new Date('2026-09-09T12:00:00+08:00')) })
+
+  it('publishes capability contract and resolves previous month', async () => {
+    expect(service.capabilities().tools.query_messages.messageTypes).toContain('file')
+    const result = await service.messages({ target: { query: 'BOBO' }, timeRange: { kind: 'previous_month' }, direction: 'any', order: 'asc', limit: 1 })
+    expect(result.status).toBe('ambiguous_contact')
+    fixture.contacts.splice(1)
+    const resolved = await service.messages({ target: { query: 'BOBO' }, timeRange: { kind: 'previous_month' }, direction: 'any', order: 'asc', limit: 1 })
+    expect(resolved.query?.resolvedTimeRange).toMatchObject({ startTime: expect.any(Number), endTime: expect.any(Number), label: '2026年8月' })
+    expect(resolved.returnedCount).toBe(1)
+  })
+
+  it('filters direction and message type, and rejects too many variants', async () => {
+    fixture.contacts.splice(1)
+    const result = await service.messages({ target: { query: 'BOBO' }, timeRange: { kind: 'all' }, direction: 'to_target', messageTypes: ['file'], limit: 1 })
+    expect(result.messages?.[0].sourceKind).toBe('file')
+    await expect(service.search({ target: { query: 'BOBO' }, timeRange: { kind: 'all' }, query: 'x', variants: ['1', '2', '3', '4', '5'] })).resolves.toMatchObject({ status: 'invalid_request' })
+  })
+
+  it('returns canonical type and attachment for the earliest non-text message', async () => {
+    fixture.contacts.splice(1)
+    const result = await service.messages({ target: { query: 'BOBO' }, timeRange: { kind: 'all' }, order: 'asc', limit: 1, excludeSystem: true })
+    expect(result.messages?.[0]).toMatchObject({ messageType: 'image', sourceKind: 'image', attachment: { kind: 'image' } })
+    expect(result.messages?.[0]).not.toHaveProperty('text')
+  })
+
+  it('sorts overview evidence while preserving the selected set and exposes sampling', async () => {
+    fixture.contacts.splice(1)
+    knowledge.search.mockResolvedValueOnce({ state: 'ready', evidence: [
+      { conversationId: 'md5-bobo', messageId: 'late', timestamp: 300, sender: 'BOBO', sourceKind: 'text', text: 'late' },
+      { conversationId: 'md5-bobo', messageId: 'early', timestamp: 100, sender: 'BOBO', sourceKind: 'text', text: 'early' }
+    ], conversationRetrieval: { totalMessages: 82, chunkCount: 4, complete: true }, voiceCoverage: undefined })
+    const result = await service.overview({ target: { query: 'BOBO' }, timeRange: { kind: 'previous_month' } })
+    expect(result.sourceCoverage).toEqual({ state: 'complete', sourceMessageCount: 82 })
+    expect(result.selection).toEqual({ mode: 'temporal_coverage', selectedEvidenceCount: 2, sampled: true })
+    expect(result.evidence?.map((item) => item.timestamp)).toEqual([100, 300])
+  })
+})