---
name: frontend_debug_log_to_file
description: 当需要把前端日志输出到后端文件（如调试目标模式、轮询状态等）时，应该索引本记忆
---

# 前端日志输出到文件

## 背景

项目已内置一套轻量级的前端 → 后端日志上报机制，用于把浏览器端的状态变化/调试信息持久化到服务器日志文件，便于复现和排查问题。

## 基础设施

### 后端端点

- 文件：`server/app_legacy.py`
- 端点：`POST /api/client_debug_log`
- 写入函数：`log_goal_mode_debug_entry(data: Dict[str, Any])`
- 日志文件：`{LOGS_DIR}/goal_mode_debug.log`
  - 宿主机模式示例：`/Users/jojo/.astrion/astrion/host/logs/goal_mode_debug.log`

### 前端函数

- 文件：`static/src/app/methods/common.ts`
- 函数：`goalModeDebugLog(event: string, payload: Record<string, any> = {})`
- 默认关闭，避免日常刷屏

## 启用方式

### 方式一：浏览器控制台临时开启（无需改代码）

```js
localStorage.setItem('goalModeDebug', '1')
// 刷新页面后生效
```

### 方式二：代码里强制开启

在 `common.ts` 中修改 `isGoalModeDebugEnabled()`，让它默认返回 `true`：

```ts
function isGoalModeDebugEnabled() {
  // ...
  return true; // 强制开启
}
```

### 方式三：运行时开关

```js
window.__GOAL_MODE_DEBUG__ = true
```

## 使用方式

在前端需要记录状态的位置调用：

```ts
import { goalModeDebugLog } from './common';

goalModeDebugLog('event_name', {
  conversationId: this.currentConversationId,
  someState: this.someState,
  // 其他需要记录的字段
});
```

调用后会：
1. 在浏览器控制台输出 `[GOAL_MODE_DEBUG]` 前缀日志
2. 通过 `fetch('/api/client_debug_log', ...)` 上报到后端
3. 后端写入 `goal_mode_debug.log`

## 注意事项

- 日志默认关闭，只有显式开启后才会输出
- `fetch` 调用使用 `void` 前缀，不会阻塞业务流程
- 上报失败会被静默捕获，不影响主流程
- 如需长期保留某类日志，应把调用代码保留在目标文件中；临时调试后建议清理调用点，只保留 `common.ts` 和后端端点基础设施

## 历史应用

- 曾用于排查"第一个对话开启目标模式后停止，目标状态被错误继承到下一个对话"的问题
- 修复代码位于 `server/tasks/api.py`：
  - `/api/tasks/<task_id>/cancel` 取消任务时同步停止工作区目标状态
  - `POST /api/tasks` 创建非目标模式任务时清理残留的活动目标状态