# AGENTS.md ## Important: File Path Convention **All file paths in this document and code references must use full absolute paths.** Examples: - ✅ `/Users/accusys/momentry_studio/src/views/PeopleView.vue` - ❌ `src/views/PeopleView.vue` - ✅ `/Users/accusys/momentry_studio/src-tauri/src/db.rs` - ❌ `src-tauri/src/db.rs` ## Workflow **Before starting any task, always create a `todowrite` with all steps listed.** Mark items `in_progress` while working and `completed` when done. ## Stack - **Frontend**: Vue 3 + TypeScript + Vite (port 5173) - **Desktop**: Tauri 2 (Rust backend in `src-tauri/`) - **Runtime**: Node.js + npm + Rust/Cargo all required ## Commands ``` npm run proxy # Start Rust proxy binary only (port 8888) npm run dev # Start Rust proxy + Vite dev server (port 5173) npm run build # vue-tsc --noEmit && vite build (typecheck + bundle) npm run preview # Preview production build npm run tauri # Alias for `cargo tauri` cargo tauri dev # Full Tauri desktop dev (builds frontend + opens native window) cargo tauri build # Full native app build (outputs to src-tauri/target/release/bundle/) ``` - **Browser dev flow**: `npm run dev` → kills old proxy on 8888 → starts `momentry-proxy` → sleeps 2s → starts Vite. Vite proxy forwards `/api/v1/*` to Rust proxy at `localhost:8888` and `/api/v2/*` directly to MarkBase at `localhost:11438`. Rust proxy handles face-crop, cluster-results, identity-matches, search-history, bookmarks, profile images locally; proxies rest to Core API at `localhost:3002`. ## Two-API Architecture (不可混淆) **Two independent backend APIs. `/api/v1/*` → Momentry Core API ONLY; `/api/v2/*` → MarkBase Core API ONLY. Never cross.** | API | Port | Namespace | Owner | Auth | |---|---|---|---|---| | **Momentry Core API** | `:3002` | `/api/v1/*` only (files, search, identities, faces, traces, agents, video-marks…) | `/Users/accusys/momentry_core` | `api_key` injected by Studio proxy | | **MarkBase Core API** | `:11438` | `/api/v2/*` only (admin, myfiles, service, auth, config, tree, products…) | `/Users/accusys/markbase/markbase-core` | Bearer token (`/api/v2/admin/login`) | **Routing rules** (`/Users/accusys/momentry_studio/src-tauri/src/proxy.rs`): - Studio proxy `:8888` is a v1/v2 gateway: `fallback_handler` routes `/api/v2/*` → `proxy_to(MARKBASE_API, inject_api_key=false)` and any other `/api/*` → `proxy_to(CORE_API, inject_api_key=true)`. MarkBase does NOT get `api_key` injected. - Vite dev proxy (`/Users/accusys/momentry_studio/vite.config.ts`): `/api/v1` → `localhost:8888`, `/api/v2` → `localhost:11438`. - **Admin data (`get_system_stats`/`list_admin_users`/`list_shares`) always comes from MarkBase `/api/v2/admin/*` in ALL modes** — these are forced to `httpCall()` in `src/api/index.ts` (no Tauri commands exist for them). - `ClientView` (`/Users/accusys/momentry_studio/src/views/ClientView.vue`) talks to MarkBase directly via `MARKBASE_URL + '/api/v2'` (bypasses Studio proxy). `start_service`/`stop_service` use `detectBaseUrl()` → MarkBase directly. ## Architecture - **Dual-mode API**: Frontend uses `apiCall()` from `src/api/index.ts` which detects `window.__TAURI__` and dispatches to either Tauri IPC (`invoke`) or HTTP to proxy at `http://0.0.0.0:8888`. - **Rust Tauri commands**: `src-tauri/src/main.rs` — 19 Tauri commands: - Core API: `search_llm_smart`, `search_agents`, `get_files`, `get_people`, `get_faces`, `get_traces`, `get_file_info` - Media: `get_thumbnail`, `get_face_thumbnail`, `get_identity_profile` - Identity: `update_identity_name`, `update_identity_status`, `update_identity_starred`, `delete_identity`, `search_identities`, `get_face_candidates`, `merge_identities`, `bind_face`, `unbind_face` - File ops: `register_file`, `process_file`, `unregister_file` - Local SQLite: `get_search_history`, `save_search_history`, `rename_search_history`, `pin_search_history`, `delete_search_history`, `get_bookmarks`, `save_bookmark`, `delete_bookmark` - **Rust HTTP proxy** (`src-tauri/src/proxy.rs`): Axum on port 8888. Routes `/api/v2/*` to MarkBase API (localhost:11438) and `/api/v1/*` to Core API (localhost:3002) with API key injection. Handles `/api/v1/search-history` and `/api/v1/bookmarks` locally via `db::` functions. Handles `/api/v1/identity/{uuid}/profile` (reads local filesystem) and `/api/v1/face-thumbnail` (downloads frame + crops bbox) locally — these mirror the Tauri IPC commands that can't be proxied to Core API. - **Per-user SQLite**: `src-tauri/src/db.rs` — Project-root `data/users/demo.sqlite` (outside `src-tauri/` to avoid dev watcher rebuilds). WAL mode enabled. Tables: `search_history`, `bookmarks`, `app_users`. `init_db()` called on app setup. - **Frontend routes**: `/search`, `/library`, `/people` (redirect `/` → `/search`) - **Frontend entry**: `src/main.ts` → `App.vue` → `router/index.ts` - **Global directive**: `v-observe` registered in `main.ts` from `src/directives/vObserve.ts` - **Composables**: `src/composables/useSearchHistory.ts` — `useSearchHistory()` and `useBookmarks()` for SQLite-backed search history and bookmarks CRUD via `apiCall`. ## Key Details - **`withGlobalTauri: true`** in `tauri.conf.json` — `window.__TAURI__` is available in the webview. - **No linter, formatter, or tests configured** — do not invent them unless asked. - **TypeScript is non-strict** (`strict: false` in `tsconfig.json`). - **CI/CD**: Shell scripts only (`ci-cd.sh`, `local-ci-cd.sh`, `setup-gitea-ci.sh`). No GitHub Actions. - **Full native build order**: `npm install` → `npm run build` → `cargo tauri build` - **Rust deps**: sqlx 0.8, rusqlite 0.32 (bundled), reqwest, tokio, tauri-plugin-shell, base64, chrono, uuid - **Core API**: `http://localhost:3002`, API key hardcoded in Rust only. - **Proxy**: `http://0.0.0.0:8888` — v1/v2 gateway: `/api/v2/*` → MarkBase (11438, no key), `/api/v1/*` → Core API with auto-injected key; handles `/api/v1/search-history` and `/api/v1/bookmarks` locally. ## Patterns - **Search thumbnails**: Use `start_frame` for frame-accurate thumbnails. Cache key format: `${file_uuid}:${start_frame}`. Not a single `file_uuid` key because same file can appear in multiple search results at different time segments. - **Store thumbnail queue**: `src/store.ts` provides `loadThumbnail()`, `loadFaceThumb()`, `loadProfile()` with max 4 concurrent requests. Always use store functions for shared data across pages. - **Page perPage limit**: Core API hangs on `per_page >= 100`. Always use `perPage ≤ 20`. The Rust `get_people` command uses a special 2-page × 100 flow (separate from frontend). - **PersonDetailView**: Uses `ensurePeople()` from store instead of direct `get_people` call. Face thumbnails go through store's `loadFaceThumb()`. Faces/candidates use `perPage: 20`. - **v-observe directive**: Global directive (`v-observe`) registered in `main.ts`. Defined in `src/directives/vObserve.ts`. Uses `IntersectionObserver` with 200px rootMargin. Includes `requestAnimationFrame` fallback for elements already visible on mount. - **SearchView empty state**: When `messages.length === 0`, shows `.ms-hero` with "Momentry Studio" + "Turn Every Moment Into Intelligence" slogan. Chat area gets `.chat--empty` class (flex-column, justify-end) to position hero near the search bar. Once messages exist, hero disappears and `.ibar` stays fixed at bottom. - **No `console.log` in *.vue files**: All debug console.log statements have been removed. Use `console.error` only for actual errors. - **No dev residue allowed (`以後不再有 dev 殘留`)**: Never commit or leave scratch/dev files in the repo — this includes tracked backup snapshots (`*.bak`, `*.bak3`, `*.base`, `*.clean`, `*.work`, `*.backup_*`), standalone dev-only binaries/scripts (e.g. `gen_password.rs`), and unused dead code. Keep backups out of git (personal temp or gitignored); delete them when done. New dev features must not introduce `console.log` (even temporary — use `console.error` or remove before commit). - **Face settings owned by Core**: `src/api/index.ts` `register_file`/`process_file` and the Rust commands in `/Users/accusys/momentry_studio/src-tauri/src/main.rs` must NOT send or read `face_settings`/`FACE_MIN_*` env vars. Core API owns the face-detection defaults server-side (see Core guide `docs_v1.0/M4_workspace/2026-08-08_face_settings_studio_guide.md`). - **Search history & bookmarks**: Stored in per-user SQLite (`data/users/demo.sqlite`), not localStorage. History items have `id`, `query`, `title`, `chat_state` (JSON-serialized Vue messages), `mode`, `pinned`, timestamps. Max 30 items; pinned sorted first. Composable `useSearchHistory()` provides `loadHistory`, `saveToHistory`, `renameHistory`, `pinHistory`, `deleteHistory`, `restoreFromHistory`. Composable `useBookmarks()` provides `loadBookmarks`, `saveBookmark`, `deleteBookmark`. - **SearchView history panel**: Dropdown with ⋯ menu per item (Pin/Unpin, Rename, Delete). +New button clears chat. Click item → restores `chat_state` JSON or runs new search. Renames via modal dialog. - **SearchView bookmark panel**: Dropdown with items from SQLite. Click → runs search. Hover shows x button to delete. - **API call snake_case**: Frontend `apiCall()` sends `camelCase` args to Tauri IPC (auto-converted by Tauri) but `snake_case` in HTTP body. `buildHttpRequest()` converts arg names for HTTP mode (e.g., `chatState` → `chat_state`). - **HistoryItem ID format**: `h_{timestamp}_{random}` e.g. `h_1718000000_abc123`. - **SQLite WAL mode + path outside src-tauri**: Database at project-root `data/users/demo.sqlite` (not inside `src-tauri/`). WAL journal mode prevents `-journal` file creation that triggers `cargo tauri dev` watcher rebuilds. Default path `../data/users/demo.sqlite` resolved from `src-tauri/` cwd. - **Video streaming**: `get_video_stream` is NOT a Tauri command. Both Tauri and browser modes use the proxy URL directly (`http://localhost:8888/api/v1/file/{uuid}/video?...`). The `