开发规范清单 · 开发者指南

所有 Python 导入使用 app.* 包路径
不在 app/services/agent.py、consumer_agent.py、voice/router.py 之外顶层导入 deepagents
避免循环导入：在函数内延迟导入（如 clear_agent_cache 在 prompt.py/subagents.py）
Consumer 路由使用 get_service_context 依赖（非 get_current_user）
Consumer Agent 创建必须传 channel 参数（web / wechat / scheduler）
路径操作统一通过 app.core.path_security.safe_join / ensure_within
文件 I/O 显式 UTF-8（encoding="utf-8"）
永远通过 api_config 或 env 读取 API URL，不硬编码
所有需要 asyncio 的 sync tool 必须通过 _main_loop + run_coroutine_threadsafe
Service manage_scheduled_tasks 仅能操作当前 conversation_id 的任务
前端图标使用 @phosphor-icons/react（不再新增 @ant-design/icons 引用）
前端组件使用函数式 + Hooks（唯一例外：ErrorBoundary）
API 调用通过 services/api.ts 统一管理
内联 borderRadius 使用 var(--jf-radius-*) 变量字符串
CSS 颜色通过 var(--jf-*) 引用，硬编码仅在 themes.css 和 themeContext.tsx
改 admin chat 时同步检查 service-chat：共享 markdown.ts 和 StreamingMessage.tsx
新加 SSE 事件类型：同时改 streamContext.tsx（admin）和 streamHandler.ts（service）
千万别为图省事在 service-chat/ 复制一份 markdown.ts — 这是历史 <<FILE:>> 媒体 bug 的根因
Scheduler 任务创建时必须带 tz_offset_hours: getTzOffset()
Tauri 路径必须经 strip_win_extended_prefix 剥离 \\?\ 前缀