一个世界建造者的最佳伙伴!
Worldbuilding database manager — Quasar + Vue 3 + Electron (GPL-3.0).
Yarn 1.x (CI pins [email protected]). Node.js 22.22.0+ (package.json engines.node). Match 22.22 locally to align with CI (.github/workflows/build.yml).
Playwright runs against production build under
dist/electron, notquasar dev. Rebuild aftersrc/,src-electron/,src/stores/, ori18n/*/documents/*.mdchanges:
yarn quasar:build:electron
Agent/maintainer guidance: AGENTS.md. Architecture depth → AGENTS + .cursor/skills/.
https://quasar.dev/start/quasar-cli — ensure Yarn global bin is on PATH.
yarn global add @quasar/cliyarnGit hooks: prepare runs husky; .husky/commit-msg → yarn lint:commit. Emergency bypass: git commit --no-verify (sparingly).
Not required to build/run app. caveman compressed agent replies — .cursor/rules/caveman-default.mdc. YAGNI minimal implementation — .cursor/rules/yagni.mdc. cavemem cross-session memory — global install + .cursor/hooks.json. Arbor (optional MCP code graph) — local gitignored .cursor/mcp.json (arbor.exe bridge), fantasia-arbor. Setup cavemem:
npm install -g cavemem
cavemem install --ide cursor
cavemem doctorRestart Cursor. Details: AGENTS.md.
CONTRIBUTING.md — fork/PR workflow, labels, Storybook VRT on forks.
| Topic | Where |
|---|---|
Two-level functions/ + *_manager.ts; *Wiring.ts for DOM/window/fs; domain barrels — see AGENTS.md Domain script barrels |
fa-two-level-architecture.mdc, fantasia-two-level-architecture |
TypeScript strict (quasar.config.ts) |
eslint-typescript.mdc |
| YAGNI / minimal diffs | yagni.mdc, fantasia-yagni |
Trees (@he-tree/vue only; QTree forbidden) |
fa-he-tree.mdc, fantasia-he-tree |
Floating Window* shared families |
fantasia-floating-windows (_sharedWindowStyling/, _sharedWindowNoteboard/) |
| List/table DnD | fa-drag-drop-lists.mdc, fantasia-drag-drop |
Reusable elements/ inputs |
AGENTS.md subsystems — FaSelectInput, FaIconPickerInput, FaLocaleTranslationsInput, FaColorPickerInput |
| Electron / IPC / preload; main security hardening | AGENTS.md, fantasia-electron-main, fantasia-electron-preload |
| Keybinds, actions, Project Settings | AGENTS.md subsystem table |
| SCSS / theme tokens | project-scss.mdc |
types/ shared interfaces |
types-folder.mdc only |
Component buckets under src/components/: dialogs/, floatingWindows/, globals/, elements/, projectUI/, other/, foundation/ (Storybook-only). Five infra helpers use _ prefix — see AGENTS.md Renderer components.
quasar dev -m electron
# or
yarn quasar:dev:electronProduction build:
yarn quasar:build:electronAfter packaging, Help → Toggle developer tools (or default F12 chord) must open DevTools — intentional product behavior in installed builds (fantasia-electron-main Packaged DevTools).
Quiet build (log → test-results/quasar-build-electron-last.log on failure):
yarn quasar:build:electron:summarizedElectron + Storybook in one terminal:
yarn app:devRelease build (CI): the manual Build App workflow (.github/workflows/build.yml, workflow_dispatch with a version input) packages the production Electron app for Windows, macOS, and Linux (AppImage, deb, rpm) and uploads the installers. It runs no test gate — verify, Playwright, and Storybook VRT are not executed in CI. Run the full local gate first:
yarn testbatch:ensure:nochange # or testbatch:ensure:change when refreshing VRT baselinesOnly trigger the CI build after that passes on your machine. Push/PR testing stays in .github/workflows/verify.yml (yarn testbatch:verify) and the pr-full-suite-* labeled-PR workflows.
yarn storybook:run
yarn storybook:build
yarn test:storybook:visual
yarn test:storybook:visual:updateStories: src/**/_tests/*.stories.ts. Workspace: .storybook-workspace/. VRT policy: fantasia-testing, storybook-stories.mdc.
Default after substantive edits: dev scoped gate — eslint on touched paths, yarn lint:typescript, stylelint on touched styles, yarn vitest run on connected specs only. Playbook: fantasia-dev-scoped-verify, dev-scoped-verify.mdc.
Agents also run 20s yarn quasar:dev:electron compile smoke after scoped gate (dev-electron-compile-check.mdc).
yarn testbatch:verifyLint (repo) + vue-tsc + Stylelint + Vitest coverage (per file: 95% / 80% / 100% / 95% via thresholds.perFile: true on src-electron, helpers/, i18n/, renderer src .ts, component .ts + .vue). Debug one step, then re-run full gate.
When required: git commit, fantasia-final-cleanup, explicit full-verify request, push/PR CI. Dev scoped gate does not substitute.
Changelog-only exception: only i18n/*/documents/changeLog.md after full gate passed on substantive work — see testing-terminal-isolation.mdc.
CI Verify (.github/workflows/verify.yml): yarn testbatch:verify only — not Playwright, Electron prod build, or Storybook VRT.
Full chained gate:
yarn testbatch:ensure:nochange # compare VRT snapshots
yarn testbatch:ensure:change # refresh VRT baselines (intentional UI only)yarn test:unit
yarn test:coverage:verifyWorkspace: vitest.config.mts → vitest/ projects (unit-electron, unit-src-renderer, unit-helpers, unit-i18n, unit-components).
Isolated userData: %APPDATA%/fantasia-archive/playwright-user-data. Serial suites reset via helpers/playwrightHelpers_universal/playwrightUserDataReset.ts.
yarn test:components
yarn test:components:single --component=dialogs/DialogAppSettings
yarn test:components:list
yarn test:e2e
yarn test:e2e:single --spec=checkDevToolsFunctionality
yarn test:e2e:single:ci --spec=checkDevToolsFunctionality.playwright.spec.ts
yarn test:e2e:listyarn test:components: src/components, src/layouts, src/pages (*.playwright.test.ts). Workspace E2E: e2e-tests/checkWorkspace*.playwright.spec.ts + helpers/playwrightHelpers_e2e/e2eWorkspaceHierarchyTree*.
Locators: data-test-locator + selectorList — playwright-tests.mdc. Keyboard: faPlaywrightKeyboardChords for cross-OS chords.
Report/videos: test-results/playwright-report/index.html. FA_PLAYWRIGHT_NO_VIDEO=1 to skip recording.
package.json)| Script | Purpose |
|---|---|
| Dev scoped gate (agents) | fantasia-dev-scoped-verify — touched lint + connected Vitest; not one yarn script |
yarn quasar:build:electron |
Production Electron build (full log). |
yarn quasar:build:electron:summarized |
Same; quiet success; log file on failure. |
yarn quasar:dev:electron |
Electron dev mode. |
yarn app:dev |
Dev + Storybook parallel. |
yarn lint:eslint |
ESLint. |
yarn lint:stylelint / lint:stylelint:fix |
Stylelint on src/ + Storybook SCSS. |
yarn lint:typescript |
vue-tsc project check. |
yarn testbatch:verify |
Full pre-commit / CI gate (lint + types + style + coverage). |
yarn testbatch:ensure:nochange |
Full gate + build + Playwright + Storybook VRT compare. |
yarn testbatch:ensure:change |
Same; update VRT snapshots. |
yarn test:unit |
Vitest (no coverage). |
yarn test:coverage:verify |
Coverage tiers (same as verify Vitest step). |
yarn test:coverage:electron / helpers / i18n / src |
Single coverage slice. |
yarn test:components / test:e2e |
Playwright suites. |
yarn test:storybook:smoke / visual* |
Storybook checks. |
yarn storybook:run / storybook:build |
Storybook dev/static. |
yarn audit:policy |
Heuristic policy report (not CI). |
yarn audit:scss-literals |
Consumer SCSS literal audit (not CI). |
yarn audit:domain-policy |
Domain policy grep (not CI). |
yarn audit:quasar-component-tokens |
$q* token audit. |
yarn audit:quasar-variables |
Feature styles/_variables.scss unused-$ audit. |
yarn audit:full |
Chained local audits (not CI). |
yarn audit:yagni |
YAGNI inventory + heuristic scan (not CI). |
yarn audit:yagni:full |
YAGNI scan + optional jscpd/depcheck. |
yarn audit:yagni:triage |
Mechanical per-file YAGNI triage JSON. |
yarn generate:icon-catalogs |
Regenerate FaIconPickerInput catalogs. |
.utility-scripts/)| Script | Role |
|---|---|
quasarBuildElectronSummarized.mjs |
Summarized Electron build |
playwrightWithArtifactTrim.mjs |
Playwright wrapper + artifact trim |
auditQuasarComponentTokens.mjs |
Quasar component token audit |
auditQuasarVariablesUsage.mjs |
Feature _variables.scss unused-$ audit |
auditScssConsumerLiterals.mjs |
Consumer SCSS literal audit |
domainPolicyGrep.mjs |
Domain policy grep |
runFullProjectAudit.mjs |
Chained local audits |
generateFaQuasarIconCatalogs.mjs |
Icon catalog generation |
policyComplianceAudit.mjs |
Policy audit |
auditYagni.mjs / auditYagniFullTriage.mjs |
YAGNI scan + full triage |
syncI18nLocaleTreeFromEnUs.mjs |
Locale tree sync (maintainer) |
batchTranslateI18nLocales.mjs |
Batch translate (maintainer) |
Quasar config — quasar.config.ts. tsconfig.json extends .quasar/tsconfig.json.
After Electron/Node version changes: clean yarn install (postinstall → electron-builder install-app-deps). If bindings missing: yarn rebuild:native, then retry dev/build.
.faproject)SQLite per project; schema user_version max 11 — docs/database/projectDB.md. Template custom fields design: templateCustomFields.md.
Project settings refresh: DialogProjectSettings IPC-reads on open (**`getProjectSe
暂无开放 Issues,或尚未同步最近议题。