Development Checklist · Developer Guide

All Python imports use app.* package paths
Do not top-level import deepagents outside app/services/agent.py, consumer_agent.py, voice/router.py
Avoid circular imports: use deferred imports inside functions (e.g., clear_agent_cache in prompt.py/subagents.py)
Consumer routes use get_service_context dependency (not get_current_user)
Consumer Agent creation must pass channel parameter (web / wechat / scheduler)
Path operations exclusively through app.core.path_security.safe_join / ensure_within
File I/O explicitly UTF-8 (encoding="utf-8")
Always read API URLs through api_config or env, never hardcode
All sync tools needing asyncio must use _main_loop + run_coroutine_threadsafe
Service manage_scheduled_tasks can only operate tasks for the current conversation_id
Frontend icons use @phosphor-icons/react (no new @ant-design/icons references)
Frontend components use functional + Hooks (sole exception: ErrorBoundary)
API calls managed through services/api.ts
Inline borderRadius uses var(--jf-radius-*) variable strings
CSS colors through var(--jf-*) references; hardcoding only in themes.css and themeContext.tsx
When changing admin chat, check service-chat too: shared markdown.ts and StreamingMessage.tsx
Adding new SSE event types: update both streamContext.tsx (admin) and streamHandler.ts (service)
Never copy markdown.ts into service-chat/ for convenience — this was the root cause of the historical <<FILE:>> media bug
Scheduler task creation must include tz_offset_hours: getTzOffset()
Tauri paths must be processed through strip_win_extended_prefix to strip \\?\ prefix