chore: 导入旧记忆备份供恢复

projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/Metrix Maintenance & Open Issues (Shared Workspace).md

@@ -0,0 +1,113 @@
+---
+title: Metrix Maintenance & Open Issues (Shared Workspace)
+type: curated
+permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-maintenance-open-issues-shared-workspace
+stable_id: 13ffa178-e9cf-4735-8da4-e1d4cf683a52
+scope: project
+project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: maintenance
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_git_commits:
+- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 29
+source_revisions:
+  memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e: '1'
+  memory:a3896ad9-d30c-4963-9232-a7d1ab571d19: '2'
+  memory:bc21af00-1127-44f8-93b7-aa484a7041c2: '1'
+  memory:5924806e-b234-49f7-b971-3c844fd07cf3: '3'
+source_dispositions:
+  processed: 29
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e
+- memory:a3896ad9-d30c-4963-9232-a7d1ab571d19
+- memory:bc21af00-1127-44f8-93b7-aa484a7041c2
+- memory:5924806e-b234-49f7-b971-3c844fd07cf3
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 162
+source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 2f4c6153-e0ba-474f-b22b-8e6dc8f0870d
+created_at: '2026-08-19T02:32:37.159033+00:00'
+updated_at: '2026-08-26T18:37:50.102629+00:00'
+tags:
+- maintenance
+- troubleshooting
+- tasks
+- preferences
+- sql
+- docker
+---
+
+## High‑Priority Open Work Items (as of 2026‑08‑26)
+
+| ID | Description | Root Cause | Source |
+|----|-------------|------------|--------|
+| **SQL‑Index‑Missing** | Add missing index for large `UPDATE JOIN` on ~5 M‑row text column (query > 2 h) | C‑05 (large query) | `memory:6c4cbc6d‑a59b‑...` |
+| **FastAPI `/health` Freeze** | Convert async blocking handler to regular `def` | C‑03 | `memory:6c4cbc6d‑a59b‑...` |
+| **Docker Exec Timeout** | Remove default 3 s socket timeout that disconnects terminals | C‑04 | `memory:6c4cbc6d‑a59b‑...` |
+| **Container‑Host Networking** | Ensure containers reliably reach host services | Identified need | – |
+| **API‑Token Permission Granularity** | Extend token model for fine‑grained actions (`container:start`) | Current policy blocks mutating ops | – |
+| **Full‑Text Audit‑Log Search** | Add MySQL `FULLTEXT` indexes & UI toggle | Keyword‑only search today | – |
+| **InterferenceETL Schedule UI** | Visual cron‑editor for `schedule` field | Text‑only schedule currently | `memory:a3896ad9‑d30c‑...` |
+| **CapacityReport CI/CD** | Automate tests & Docker image builds per release | Manual sync currently | – |
+| **Shiki Theme Sync** | Keep Shiki highlighting in sync with UI dark/light theme | Pending implementation | – |
+| **Internal PyPI Cache Eviction** | Background job to purge old wheels when size/TTL limits hit | No eviction policy | – |
+| **Terminal Copy‑Paste on Windows** | Add error handling & UI notification for pipe failures | Sporadic failures observed | – |
+| **Column‑Width Persistence** | Store layout metadata via user‑preferences API (instead of only `localStorage`) | Current per‑page only | – |
+| **Duplicate‑CGI Merge Strategy** | Configurable (`highest|latest|average`) merge for duplicate rows | Fixed to “highest DBM” | – |
+
+## Resolved Tasks (Verified at 2026‑08‑26 checkpoint)
+
+- **FastAPI `/health` async → def conversion** – ✅ (`memory:fb67062d‑89fa‑...`).
+- **Docker exec timeout removal** – ✅ (`memory:6c4cbc6d‑a59b‑...`).
+- **Shiki theme sync implementation** – ✅ (`memory:fb67062d‑89fa‑...`).
+- **InterferenceETL cron‑editor UI** – ✅ (`memory:6d022bb5‑053d‑...`).
+- **CapacityReport second instance deployment** – ✅ (`memory:2a61dd7b‑d069‑...`).
+
+## Troubleshooting Summary
+
+| # | Symptom | Cause | Solution |
+|---|---------|-------|----------|
+| 1 | Windows directory rename locked | IDE holds handle on `.git` | Stop IDE, rename, `git submodule sync` |
+| 2 | `/health` endpoint never returns | Async handler performed blocking I/O | Convert to regular `def` |
+| 3 | Docker `exec` sessions disconnect after ~3 s | Default socket timeout | Call `socket.settimeout(None)` after `exec_start` |
+| 4 | Missing `api_enabled` flag → `forbidden` error | Config lacks flag | Add `api_enabled: bool = True` in `core/config.py` |
+| 5 | Hard‑coded credentials in `pypi_mirror.py` | Placeholder left in code | Use env vars or Vaultwarden |
+| 6 | `create-module.mjs` typo (`___SNAKE___snapshot`) | Template typo | Fix placeholder |
+| 7 | Empty `pytest.ini` | No test files | Add tests or update config |
+| 8 | Generic `except Exception: pass` in container exec WS | Swallows errors | Log exception & close WebSocket |
+| 9 | Permission expansion not applied (`resource:*` → read) | Expansion logic missing | Ensure `expand_permissions` runs during seeding |
+|10| Shiki theme not syncing on UI theme change | Shiki instance not updated | Watch `appStore.dark`, call `shiki.setTheme` |
+|11| Terminal copy‑paste fails on Windows named pipes | Missing error handling | Add UI toast & fallback to TCP |
+|12| Column‑width reset on reload | Width stored only in `localStorage` | Persist via `/api/user/preferences` |
+|13| Duplicate CGI merge strategy undefined | No config option | Add `duplicate_cgi_merge` setting |
+|14| Internal PyPI cache grows unbounded | No eviction policy | Background job to delete oldest wheels when limits exceeded |
+
+## Ongoing Development Preferences (scenario level)
+
+1. **Workflow Order** – Implement → Clean → Memory → Docs → Commit (Chinese‑first, KISS/YAGNI). (source: `global_guidance_memory:5924806e-...`, `global_guidance_document:e4fc35f2-...`)
+2. **Git Commit Convention** – `type: 中文一句话描述` (e.g., `feat: 添加用户登录`). (source: `global_guidance_document:d3a20d44-...`)
+3. **Environment** – Development on Windows + WSL2 + Docker Desktop; all commands must be Windows‑compatible. (source: `global_guidance_document:6973450e-...`, `global_guidance_document:8a861a5f-...`)
+
+These preferences are recorded at the **scenario** level for the *development* workspace and do not create global settings.
+
+## Tags
+
+`[maintenance]` `[troubleshooting]` `[tasks]` `[preferences]` `[sql]` `[docker]`

projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/Metrix Offline Deployment & Sub‑module Migration Guide.md

@@ -0,0 +1,117 @@
+---
+title: Metrix Offline Deployment & Sub‑module Migration Guide
+type: curated
+permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-offline-deployment-sub-module-migration-guide
+stable_id: bb1539bd-c7f2-4d57-9257-8e4b2b4672cb
+scope: project
+project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: deployment
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_git_commits:
+- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 29
+source_revisions:
+  memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e: '1'
+  memory:a3896ad9-d30c-4963-9232-a7d1ab571d19: '2'
+  memory:bc21af00-1127-44f8-93b7-aa484a7041c2: '1'
+  memory:5924806e-b234-49f7-b971-3c844fd07cf3: '3'
+source_dispositions:
+  processed: 29
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e
+- memory:a3896ad9-d30c-4963-9232-a7d1ab571d19
+- memory:bc21af00-1127-44f8-93b7-aa484a7041c2
+- memory:5924806e-b234-49f7-b971-3c844fd07cf3
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 162
+source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 2f4c6153-e0ba-474f-b22b-8e6dc8f0870d
+created_at: '2026-08-19T02:32:32.719008+00:00'
+updated_at: '2026-08-26T18:37:45.656797+00:00'
+tags:
+- deployment
+- docker
+- fastapi
+- vue
+- ci
+- offline
+- security
+---
+
+## Overview
+
+The **Metrix** platform is a modular FastAPI + Vue 3 system deployed via Docker. The architecture consists of an API gateway, core modules (containers, database, scripts, storage, internal PyPI), and a SPA front‑end built with Vite and Naïve‑UI. All modules are auto‑registered through `APP_MODULE` and use an action‑based RBAC model.
+
+| Layer | Component | Key notes |
+|------|-----------|-----------|
+| API Gateway / FastAPI Core | `git:server/app/main.py` | FastAPI factory, OpenAPI, CORS, SPA fallback |
+| Module Registry | `git:server/app/modules/registry.py` | Discovers `APP_MODULE` objects, validates keys & deps |
+| Permission Framework | `git:server/app/core/permissions.py` | Action‑based RBAC; `action:* → read` |
+| Security Utils | `git:server/app/core/security.py` | PBKDF2‑SHA256 hashing, `mtx_` API‑tokens, Fernet secrets |
+| Database Sub‑system | ORM models, `git:server/app/db/init.py`, migrations | SQLAlchemy sessions, alembic‑style registry |
+| Containers Module | Docker client, WS xterm.js terminal | `modules/containers/...` |
+| Storage API | FTP/SFTP adapters, file‑tree service (depth/size caps) |
+| Offline Docker Deployment | `scripts/build_docker.py` → `metrix‑app‑latest.tar` (+ optional MySQL & internal PyPI) |
+| Front‑End SPA | Vue 3 + TypeScript + Vite + Naïve‑UI; i18n (EN/ZH), dark/light themes, Monaco + Shiki, Playwright tests |
+| CI / Regression | Playwright end‑to‑end suite (`tests/regression/framework.spec.ts`) |
+
+## Current Deployment State (as of 2026‑08‑26)
+
+- **Backend**: FastAPI fully running; all core modules (`containers`, `database`, `scripts`, `storage`, internal PyPI) registered via `APP_MODULE`. Action‑based RBAC active; Vaultwarden is the source of credentials (`global_guidance_memory:105b328f‑…`).
+- **Frontend**: Vue 3 SPA stable, English/Chinese toggle, dark/light theme sync (Shiki pending). The new **DatabasePanel** supports keyword search (`POST /api/database/table/query`) with pagination and filter persistence.
+- **Instances**: A second instance `capacityrepost‑web:113ff5c` is live; health‑check (`/health`) returns **200** and the image SHA‑256 matches the offline bundle.
+- **Validation**: Example `sector` table queries return expected row counts; UI renders correctly at both 1440 px and 720 px widths.
+- **Conclusion**: The system is **stable**; only high‑priority open items remain (Shiki theme sync, fine‑grained API‑token permissions).
+
+## Deployment Artifacts
+
+- **Docker images** are built with `scripts/build_docker.py`, producing `metrix‑app‑latest.tar`. The tar contains the FastAPI image, the Vue SPA static assets, and an optional MySQL image for air‑gapped environments.
+- **Compose files** define the primary service (`metrix‑app`) and the secondary `capacityrepost‑web` with its own MySQL container.
+- **Internal PyPI server** (`pypiserver` container) provides offline wheels; the UI is exposed at `/pypi`.
+- **Offline bundle** supports deployments without Internet access.
+
+## Key Deployment Decisions
+
+| Decision ID | Summary | Rationale | Status |
+|------------|----------|-----------|--------|
+| `e71d9113‑be70‑4792‑8a7d‑81df157ea9a0` | Keep **CapacityReport** as independent sub‑module + Docker image | Isolated UI & historic data handling | Implemented |
+| `52d53ae2‑ce5b‑4207‑9813‑0c9d3de029ce` | Switch editor highlighting to **Shiki** | Monaco mis‑highlights multiline f‑strings | Integrated (theme sync pending) |
+| `761650df‑f1df‑4e5a‑b23a‑adf2d01d5c9f` | Adopt **action‑based permission model** | Simplify checks, avoid page rule duplication | All modules migrated |
+| `34271d12‑a706‑491b‑a06b‑f561e81f7346` | Consolidate script‑run retention to `{max_count, max_days}` | Remove overlapping policies | Unified |
+| `cf3e85fe‑dcf3‑4af3‑9a17‑edfe63b2f56c` | Freeze local `docs/project_context.md`; **MemRelay only** stores memory | Avoid bidirectional sync, per user request | File read‑only, MemRelay source of truth |
+| `5924806e‑b234‑49f7‑b971‑3c844fd07cf3` | Formalise **workflow**: Chinese‑first, KISS/YAGNI, ordered steps (implement→clean→memory→docs→commit) | Standardise practice | Documented, tooling enforced |
+| *Docker‑socket mount* | Mount host Docker socket into `metrix‑app` | Enables host‑level container management for scripts | Documented, admin‑only |
+| *Offline bundle* | Tarred images + compose files for air‑gapped deployment | Offline environments cannot pull from Docker Hub | `scripts/build_docker.py` creates bundle |
+| *Internal PyPI server* | Run `pypiserver` container, serve wheels offline | Remove external PyPI dependency | Implemented, UI `/pypi` added |
+
+## Deployment‑Related Preferences (scenario level, development workspace)
+
+1. **Language** – Daily communication in **中文** unless otherwise requested. (source: `global_guidance_memory:7429c22e-...`, `global_guidance_document:6973450e-...`)
+2. **Credential Handling** – All secrets must be fetched from **Vaultwarden**; only the credential name is stored in memory. (source: `global_guidance_memory:105b328f-...`, `global_guidance_document:2b47472d-...`)
+3. **FastAPI Async Pitfall** – Avoid blocking I/O inside `async def`; move to `def` or thread‑pool. (source: `global_guidance_document:e4fc35f2-...`)
+4. **Docker Exec Timeout** – Disable default 3 s timeout via `socket.settimeout(None)`. (source: `global_guidance_document:e4fc35f2-...`)
+5. **KISS & YAGNI** – Keep implementations minimal, no speculative dependencies. (source: `global_guidance_memory:bf88c265-...`, `global_guidance_document:2b47472d-...`)
+
+These preferences are recorded as **scenario‑level** because the output scope is *project* and cannot promote them to global.
+
+## Tags
+
+`[deployment]` `[docker]` `[fastapi]` `[vue]` `[ci]` `[offline]` `[security]`

projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/Metrix System Architecture Overview.md

@@ -0,0 +1,73 @@
+---
+title: Metrix System Architecture Overview
+type: curated
+permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-system-architecture-overview
+stable_id: 44fc1143-7dee-4e0a-8086-42b65f39e0de
+scope: project
+project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: architecture
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_git_commits:
+- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 29
+source_revisions: {}
+source_dispositions:
+  processed: 29
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids:
+- git:server/app/main.py
+- git:server/app/modules/registry.py
+- git:server/app/core/permissions.py
+- git:server/app/core/security.py
+- git:server/app/db/init.py
+- git:server/app/migrations/registry.py
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 162
+source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 2f4c6153-e0ba-474f-b22b-8e6dc8f0870d
+created_at: '2026-08-19T02:32:26.402300+00:00'
+updated_at: '2026-08-26T18:37:29.455265+00:00'
+tags:
+- architecture
+- fastapi
+- vue
+- modules
+---
+
+## Architecture Overview (2026‑08‑26)
+
+| Layer | Component | Key Notes |
+|------|-----------|-----------|
+| **API Gateway / FastAPI Core** | `git:server/app/main.py` | FastAPI app factory, OpenAPI, CORS, SPA fallback |
+| **Module Registry** | `git:server/app/modules/registry.py` | Discovers `APP_MODULE` objects, validates keys & deps |
+| **Permission Framework** | `git:server/app/core/permissions.py` | Action‑based RBAC; `action:* → read` |
+| **Security Utils** | `git:server/app/core/security.py` | PBKDF2‑SHA256 hashing, `mtx_` API‑tokens, Fernet secrets |
+| **Database Sub‑system** | ORM models, `git:server/app/db/init.py`, migrations | SQLAlchemy sessions, alembic‑style registry |
+| **Containers Module** | Docker client, WS xterm.js terminal | `modules/containers/...` |
+| **Database Module** | Export/Import, APScheduler jobs, pagination |
+| **Scripts Execution Platform** | Preset Docker images, quota, retention policies |
+| **Storage API** | FTP/SFTP adapters, file‑tree service (depth/size caps) |
+| **Offline Docker Deployment** | `scripts/build_docker.py` → `metrix‑app‑latest.tar` (+ optional MySQL & internal PyPI) |
+| **Front‑End SPA** | Vue 3 + TypeScript + Vite + Naïve‑UI; i18n (EN/ZH), dark/light themes, Monaco + Shiki, Playwright tests |
+| **CI / Regression** | Playwright end‑to‑end suite (`tests/regression/framework.spec.ts`) |
+
+**Module Interaction Flow** – router guard → auth store → API client → registered pages → background job polling.
+
+The architecture reflects the stable state captured on **2026‑08‑26** (see Current State).

projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/Metrix – Common Issues & Resolutions.md

@@ -0,0 +1,66 @@
+---
+title: Metrix – Common Issues & Resolutions
+type: curated
+permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-common-issues-resolutions
+stable_id: 1e1b9a7e-5897-4c82-b267-279a8c54b150
+scope: project
+project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
+workspace_type: development
+usage_profile_id: null
+preference_context: development
+document_type: troubleshooting
+revision: 2
+source_memory_ids: []
+source_checkpoint_ids: []
+source_file_ids: []
+source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_git_commits:
+- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
+source_agent_sync_ids: []
+model_connection: Sub2API
+model_name: openai/gpt-oss-120b
+source_count: 29
+source_revisions: {}
+source_dispositions:
+  processed: 29
+  unchanged: 0
+  unsupported: 0
+  skipped: 0
+cited_source_ids: []
+job_cited_source_ids: []
+conflicts: []
+supersedes: []
+preferences: []
+source_cursor: 162
+source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
+prompt_version: 2026-08-12.3
+schema_version: '3'
+curation_job_id: 2f4c6153-e0ba-474f-b22b-8e6dc8f0870d
+created_at: '2026-08-19T02:32:30.066112+00:00'
+updated_at: '2026-08-26T18:37:41.797298+00:00'
+tags:
+- troubleshooting
+- issues
+---
+
+## Troubleshooting Summary (compiled from baseline)
+
+| # | Symptom | Cause | Solution |
+|---|---------|-------|----------|
+| 1 | Windows directory rename locked (`git status` “cannot move”) | IDE holds handle on `.git` | Stop IDE, move `.git` aside, rename, move back, `git submodule sync` |
+| 2 | `/health` endpoint never returns | Async handler performed blocking I/O | Convert handler to regular `def` (thread‑pool) |
+| 3 | Docker `exec` sessions disconnect after ~3 s | Default socket timeout | After `exec_start`, call `socket.settimeout(None)` |
+| 4 | Missing `api_enabled` flag → `forbidden` error | Flag absent in `core/config.py` | Add `api_enabled: bool = True` (configurable) |
+| 5 | Hard‑coded credentials in `pypi_mirror.py` | Placeholder left in code | Use environment variables or Vaultwarden for secrets |
+| 6 | `create-module.mjs` typo (`___SNAKE___snapshot`) | Template typo | Fix placeholder to correct name |
+| 7 | `pytest.ini` points to empty test dir | No tests present | Add test files or update config |
+| 8 | Generic `except Exception: pass` in container exec WS | Swallows errors | Replace with logged exception + WebSocket close |
+| 9 | Permission expansion not applied (`resource:* → read`) | Expansion logic missing | Ensure `expand_permissions` runs during seeding |
+|10| Shiki theme not syncing on UI theme change | Shiki instance not updated | Watch `appStore.dark`, call `shiki.setTheme` |
+|11| Terminal copy‑paste fails on Windows named pipes | Missing error handling | Add UI toast & fallback to TCP |
+|12| Column‑width reset on reload | Width stored only in `localStorage` | Persist via `/api/user/preferences` |
+|13| Duplicate CGI merge strategy undefined | No config option | Add `duplicate_cgi_merge` setting (`highest|latest|average`) |
+|14| Internal PyPI cache grows unbounded | No eviction policy | Background job to delete oldest wheels when limits exceeded |
+|15| Re‑reported missing `api_enabled` flag (duplicate) | See #4 | — |
+
+These solutions have been applied where marked **✅ Completed** in the task list. Remaining items are tracked in the **High‑Priority Open Work Items** table (source `curated_baseline:13ffa178‑e9cf‑4735‑8da4‑e1d4cf683a52`).