chore(frontend): 补充状态与服务边界注释

frontend/src/services/agentService.ts

@@ -3,6 +3,7 @@ import { SseClient } from './sseClient'
 import type { AgentRun, AgentEvent, ApiAgentRun, OperationResponse, PageMeta, ToolDefinition, PermissionRequest } from '@/contracts'
 
 function toAgentRun(run: ApiAgentRun): AgentRun {
+  // API 的 token_usage 是累计值，UI 模型预留了输入/输出拆分字段。
   return {
     run_id: run.run_id,
     status: run.status,
@@ -67,6 +68,7 @@ export function streamAgentEvents(
     onOpen?: () => void
   }
 ): SseClient {
+  // 将通用 SSE 包装成领域事件，Store 无需了解传输层 envelope。
   const client = new SseClient({
     url: `/api/agent/runs/${runId}/events`,
     method: 'GET',

frontend/src/services/apiClient.ts

@@ -1,5 +1,6 @@
 import type { ApiError, ErrorResponse } from '@/contracts'
 
+// 所有 HTTP 请求都经过此边界，以统一地址、请求追踪和错误契约。
 const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? import.meta.env.VITE_API_BASE ?? ''
 
 export function resolveApiUrl(path: string): string {
@@ -63,6 +64,7 @@ async function request<T>(path: string, options: RequestOptions = {}): Promise<T
       return resp as unknown as T
     }
 
+    // 后端约定返回 ErrorResponse；代理或网关的非 JSON 错误仍降级为 HTTP 状态码。
     let errBody: ErrorResponse | null = null
     try {
       errBody = (await resp.json()) as ErrorResponse

frontend/src/services/sseClient.ts

@@ -54,6 +54,7 @@ export class SseClient {
       this.connected = true
       onOpen?.()
 
+      // 一个 UTF-8 字符或 SSE 行可能横跨多个网络分片，必须累积后再按空行派发。
       const decoder = new TextDecoder('utf-8')
       let eventName = 'message'
       let dataLines: string[] = []
@@ -117,6 +118,8 @@ export class SseClient {
     this.controller.abort()
   }
 
+  // TODO(streaming): Agent 事件持久化后，增加 Last-Event-ID 与指数退避重连。
+
   isConnected() {
     return this.connected
   }

frontend/src/services/workspaceService.ts

@@ -1,7 +1,7 @@
 import type { FileNode } from '@/contracts'
 
-// Mock workspace service for web dev mode
-// In Tauri environment this will use Tauri IPC commands
+// Web 开发模式使用内存实现，服务签名保持与未来桌面文件系统适配器一致。
+// TODO(desktop): Tauri Host 就绪后通过 IPC 替换 Mock，并保留路径规范化与错误映射。
 
 export interface VaultInfo {
   path: string
@@ -251,5 +251,8 @@ export function deleteFile(path: string): Promise<void> {
 }
 
 export function moveFile(sourcePath: string, targetPath: string): Promise<void> {
+  // Mock 文件树由 Store 同步更新；真实实现必须在 Host 侧执行原子移动。
+  void sourcePath
+  void targetPath
   return Promise.resolve()
 }