agent-Specialization/.astrion/memory/frontend_debug_log_to_file.md

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

前端日志输出到文件

背景

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

基础设施

后端端点

• 文件：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> = {})
• 默认关闭，避免日常刷屏

启用方式

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

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

方式二：代码里强制开启

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

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

方式三：运行时开关

window.__GOAL_MODE_DEBUG__ = true

使用方式

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

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 创建非目标模式任务时清理残留的活动目标状态