Guidance for AI agents working in this repository.
Project: EndProtocol — a Tauri 2.x + React 19 desktop app integrating the Skland (森空岛) / Hypergryph APIs: multi-account management (Arknights: Endfield and Arknights), character data, daily attendance, gacha stats, game launcher, self-updater.
Stack: TypeScript/React 19/Vite/Tailwind (frontend in src/), Rust/tokio/reqwest (backend in src-tauri/src/), IPC via Tauri invoke + emit/listen.
- Find what you need: Open
docs/README.md— the master index with quick lookup tables. - Read before coding: Check
docs/*.mdguides (frontend, backend, API, cards) for conventions. - Update indexes: If you change files/symbols/commands/configs, update the matching reference docs in the same commit.
| File | Purpose | Audience |
|---|---|---|
| README.md | Product intro, features, download, quick start | Users |
| docs/README.md | Developer documentation hub: lookup tables, inventory, maintenance rules | Developers |
| docs/reference/ | Per-file reference with symbol→line tables, call chains, config keys | Developers |
⚠️ Never start by browsing the filesystem. Always look up targets in the documentation first.
Use these lookup paths based on your question:
| Question | Document |
|---|---|
| Where is feature X implemented? | docs/README.md §1 quick lookup table |
| What does this file do, which symbols are on which line? | Matching file under docs/reference/ |
| Which Tauri command does X, and who calls it? | docs/reference/ipc_index.md |
| Signature / params / return / internal call chain of a command? | docs/reference/backend/commands.md |
| Which HTTP endpoint / config key / event does a service use? | docs/reference/backend/services_account.md, services_skland.md, services_launcher.md, services_others.md |
| Props of a UI component, fields of a type, i18n namespace? | docs/reference/frontend/ui_components.md, types_locales_styles.md |
| How to write code here (conventions, extension points)? | docs/*.md guides (frontend, backend, api, card_*) |
- 27 reference docs covering every source file
- Written in Chinese
- Contains: symbol→line tables, invoked commands, config keys, events, endpoints
- Line numbers are locating aids, not contracts — they drift as code changes
✅ Open source code only when:
- The reference documentation lacks the detail you need, or appears stale
- You are about to change behavior — read the whole file (and its reference section) first
- You need exact current signatures/types for a call
❌ Do not open source code if:
- The reference doc already answers your question
- You're just exploring or browsing
Before writing any code:
docs/frontend_development.mddocs/backend_development.mddocs/api_communication.mddocs/card_development.mddocs/card_configuration.md
| Area | Rule |
|---|---|
| Frontend logging | Use src/utils/logger.ts — never bare console.log |
| User-visible text | i18next (src/locales/), never hard-coded strings |
| Frontend→backend calls | Wrap invoke in src/utils/*Service.ts with types and explicit failure returns |
| Backend errors | Result<T, AppError> (src-tauri/src/utils/error.rs); async for I/O; tracing/log_* for logs |
| Styling | Tailwind + glass components in src/components/ui/glass |
| Icons | Use icon components from lucide/morphicons (or existing SVG icon components). Persist icon identifiers, not emoji characters |
| State/config | ConfigService on the backend (app_config.json, dotted keys) — no ad-hoc file writes |
Never read or modify generated/distribution folders:
dist/target/node_modules/src-tauri/gen/
Do not use tools that control or observe the screen unless the current prompt explicitly allows it.
This covers the computer tool (inspect, screenshot, click, type, key, scroll, drag, move, focus, set_value, open_url) and any equivalent OS-level automation: UI Automation / Win32 window driving, SendKeys, mouse or keyboard hooks, and desktop screenshot capture.
- Default is denied. Silence in the prompt is not permission — permission must be stated explicitly in the current prompt.
- Permission is per-turn and per-action. It covers only what that prompt names, and it does not carry over to later turns.
- Denied does not mean blocked. If a task appears to need screen control, say what needs to happen on screen and hand that step to the user instead of doing it.
No lint or test scripts are configured. Use:
npm run build # Vite build (frontend type/syntax check)
npm run dev # Vite dev server
cargo check # Run inside src-tauri/ (existing warnings are expected)Tauri can only bundle an AppImage on Linux — pnpm tauri build --bundles appimage on Windows exits without producing anything, and cross-compiling from Windows is not supported. On a Windows host, build inside WSL2 (Ubuntu 24.04 on this machine).
-
Node ≥ 24 and pnpm 10
-
Rust via rustup.
~/.cargo/binis not on the login-shell PATH, so alwaysexport PATH="$HOME/.cargo/bin:$PATH"in build scripts, otherwise the Tauri CLI fails withfailed to run 'cargo metadata' command … No such file or directory. -
System packages:
libwebkit2gtk-4.1-dev,libayatana-appindicator3-dev,librsvg2-dev,libssl-dev,patchelf,build-essential,pkg-config,squashfs-tools(formksquashfs). All are present on this machine; installing more requires the WSL sudo password. -
Build with
CC=gcc-13. The default gcc 15 emits.base64assembler directives that binutils 2.42 cannot parse, which breaks theringcrate:/tmp/ccXXXX.s:102071: Error: unknown pseudo-op: `.base64'CC=gcc-13fixes it. Downgradingringdoes not — the version is irrelevant.
-
Copy the project to the WSL native filesystem. Never build over
/mnt/f: 9p is slow and the Windowsnode_modulescontains wrong-platform binaries.rm -rf "$HOME/build/endprotocol" && mkdir -p "$HOME/build/endprotocol" tar -C /mnt/f/endprotocol \ --exclude=node_modules --exclude=target --exclude=dist --exclude=dist-linux \ --exclude=.git --exclude=.pnpm-store -cf - . | tar -C "$HOME/build/endprotocol" -xf -
-
Disable updater artifact signing in the WSL copy only.
createUpdaterArtifacts: trueaborts bundling whenTAURI_SIGNING_PRIVATE_KEYis unset:node -e "const fs=require('fs');const p='src-tauri/tauri.conf.json';const c=JSON.parse(fs.readFileSync(p,'utf8'));c.bundle.createUpdaterArtifacts=false;fs.writeFileSync(p,JSON.stringify(c,null,2)+'\n')"The checked-in
src-tauri/tauri.conf.jsonmust staytrue; this edit only exists so a local unsigned build can finish. -
Install and build:
export PATH="$HOME/.cargo/bin:$PATH" export CC=gcc-13 cd "$HOME/build/endprotocol" pnpm install --frozen-lockfile pnpm tauri build --bundles appimage
A clean release build of the Rust backend takes roughly 2–3 minutes on 16 cores.
This is the normal outcome in WSL, not a code problem. linuxdeploy-plugin-appimage downloads the AppImage runtime from github.com, and WSL cannot reach it: the Windows proxy listens on 127.0.0.1:10808 only, which is unreachable from WSL2 in NAT mode. By that point the AppDir is already fully populated (AppRun, .desktop, icons, usr/lib deps, GTK hooks), so finish the last step by hand.
Download both files on the Windows side, through the local proxy:
curl.exe -x http://127.0.0.1:10808 -L -o "$env:TEMP\runtime-x86_64" `
https://github.com/AppImage/type2-runtime/releases/download/continuous/runtime-x86_64
curl.exe -x http://127.0.0.1:10808 -L -o "$env:TEMP\appimagetool-x86_64.AppImage" `
https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImageThen package the existing AppDir inside WSL:
cp /mnt/c/Users/<user>/AppData/Local/Temp/runtime-x86_64 /tmp/
cp /mnt/c/Users/<user>/AppData/Local/Temp/appimagetool-x86_64.AppImage /tmp/
chmod +x /tmp/appimagetool-x86_64.AppImage
cd "$HOME/build/endprotocol/target/release/bundle/appimage"
ARCH=x86_64 VERSION=0.1.0 APPIMAGE_EXTRACT_AND_RUN=1 /tmp/appimagetool-x86_64.AppImage \
--no-appstream \
--runtime-file /tmp/runtime-x86_64 \
endprotocol.AppDir \
endprotocol_0.1.0_amd64.AppImageCopy the result back to the repo (the folder is gitignored):
wsl -d Ubuntu-24.04 -- cp ~/build/endprotocol/target/release/bundle/appimage/endprotocol_0.1.0_amd64.AppImage /mnt/f/endprotocol/dist-linux/./endprotocol_0.1.0_amd64.AppImage --appimage-offset # prints the embedded runtime size (944632 with the continuous runtime)
./endprotocol_0.1.0_amd64.AppImage --appimage-extract # must list usr/bin/endprotocol and endprotocol.desktop
file endprotocol_0.1.0_amd64.AppImage # ELF 64-bit LSB pie executable, x86-64- Unsigned local builds cannot self-update. Release builds get their updater signature from
TAURI_SIGNING_PRIVATE_KEY(see.github/workflows/release.yml). - glibc baseline. A WSL Ubuntu 24.04 build targets glibc 2.39 +
webkit2gtk-4.1and may fail to start on older distros. CI deliberately builds onubuntu-22.04for wider compatibility. - Local version stays
0.1.0. CI rewritespackage.jsonandtauri.conf.jsonfrom the git tag; local builds keep the checked-in version. - Never drive this through
wsl … bash -lc '<script>'from PowerShell. Quotes get mangled (a script containing"$PATH"arrives broken and bash dies on the parentheses in the inherited Windows PATH). Write the snippet to a.shfile and runwsl -d Ubuntu-24.04 -- bash /tmp/script.sh.
Outdated documentation becomes a trap. You must update indexes in the same commit as your code changes.
If your change adds, removes, or renames any of: files, exported symbols/components/methods, Tauri commands, config keys, events, card directories:
| Change Type | Required Updates |
|---|---|
| General refactoring | Affected reference doc — keep its format: ## <file path> → 职责 / 导出 / 主要依赖 → ` |
New/removed/renamed #[tauri::command] |
Regenerate docs/reference/ipc_index.md (script: docs/README.md §5.1) and add/remove the row in docs/reference/backend/commands.md |
| New page/component/service/card | Add a section to the matching docs/reference/{frontend,backend}/*.md |
| New card plugin | Follow docs/card_development.md and record it in the relevant cards_*.md |
| Changed entry point / directory layout / feature map | Update docs/README.md (quick lookup table) and docs/project_structure.md |
| Technical implementation details | Move from README.md to docs/ — README.md is marketing-only |
code changed + verified + indexes updated, all in one commit-ready state
If a doc contradicts the code, the code wins. Fix the doc and explain why in your commit summary.
docs/
├── README.md # Entry point: quick lookup table, doc inventory, maintenance rules
├── user_guide.md # User-facing usage guide
├── development.md # Developer setup, build, CI/CD, commit rules
├── project_structure.md # Directory layout, runtime flow
├── frontend_development.md # Frontend conventions & extension points
├── backend_development.md # Rust layering, conventions, crypto/signing
├── api_communication.md # IPC contract, data flows
├── card_development.md # Card plugin system guide
├── card_configuration.md # Card settings storage & migration
└── reference/ # Per-file references (generated by reading the code)
├── ipc_index.md # 144 commands ↔ definition ↔ frontend callers
├── frontend/ (18 docs) # Frontend file references
└── backend/ (8 docs) # Backend file references
Every commit must follow Conventional Commits with a prefix:
<type>(<scope>): <lowercase imperative summary, no trailing period>
<optional body: one bullet per coherent change>
<optional trailers, e.g. Co-authored-by: ...>
feat, fix, docs, style, refactor, perf, test, build, ci, chore
Optional but recommended when the change belongs to one area:
feat(launcher)fix(updater)docs(agents)
Plain prefixes are valid for cross-area changes:
feat: enable cross-platform builds and updates
Preferred approach: Keep one coherent change per commit.
| Strategy | Example |
|---|---|
| ✅ One commit | code + its required doc-index updates (§7) |
| ✅ Separate commits | unrelated work (repo meta docs, tooling, formatting) |
Before pushing:
- Run verification commands (§5):
npm run build,cargo check - Ensure indexes are updated (§7)
- Verify commit has a proper prefix
- Avoid mixing unrelated features into one commit
Issues and specs live in this repo's GitHub Issues (gh CLI). See docs/agents/issue-tracker.md.
Five canonical roles mapped to the default label strings (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See docs/agents/triage-labels.md.
single-context — one root GLOSSARY.md and docs/adr/. See docs/agents/domain.md.
🎯 Goal: Find something? → docs/README.md
💻 Writing code? → Read docs/*.md guides first
📝 Changing files? → Update reference docs in the same commit
🚫 Generated folders? → Never touch dist/, target/, node_modules/, src-tauri/gen/
🖥️ Screen control? → Denied unless the current prompt explicitly allows it, see §4
🐧 Linux AppImage? → WSL2 + CC=gcc-13, see §6
✅ Definition of done? → code + verify + docs = one commit