37 lines
3.1 KiB
Markdown
37 lines
3.1 KiB
Markdown
# Web Tools Agent Guide
|
|
|
|
Before changing this project, read `README.zh-CN.md` in full. Its architecture constraints, extension procedure, validation checklist, and release steps are authoritative.
|
|
|
|
## Project identity
|
|
|
|
- This is a self-hosted Vue 3 + TypeScript browser-local tools application with a zero-dependency Node.js static/configuration server.
|
|
- `package.json` is the authoritative application version. The default production port is `9000`.
|
|
- `shared/tool-catalog.json` is the authoritative tool catalog; `shared/default-navigation.json` defines first-run ordering.
|
|
- `README.zh-CN.md` is the complete product, architecture, deployment, extension, and AI handoff document. `README.md` is only the universal entry point.
|
|
- Windows Server uses `web-tools.ps1`; containers use `Dockerfile` and `docker-compose.yml`.
|
|
|
|
## First actions in a new session
|
|
|
|
1. Read `README.zh-CN.md`, then inspect `git status --short --branch` and preserve all existing worktree changes.
|
|
2. Read the closest existing tool, its `src/lib/` logic, and related tests before adding or changing behavior.
|
|
3. Keep default production port references synchronized in `server/index.mjs`, `web-tools.ps1`, `Dockerfile`, `docker-compose.yml`, `.env.example`, and deployment documentation.
|
|
4. Run `npm run check`; for deployment changes also validate PowerShell syntax and Docker Compose configuration when those tools are available.
|
|
|
|
Key rules:
|
|
|
|
- Preserve the anonymous, no-login, no-database design. Tool calculations are isolated in each browser tab; only navigation order is shared globally.
|
|
- Never send tool input, keys, text, or images to the server or a third party.
|
|
- Keep each tool independently lazy-loaded through `src/tools/registry.ts`.
|
|
- Put testable computation in `src/lib/` and cover it in `tests/`.
|
|
- Preserve the documented file, record, image, random-output, syntax-rendering, and request-size limits. Update the limits table and tests when any limit changes.
|
|
- Preserve the firmware Hash byte stream contract: sorted effective blocks without gap filling, or an 8-byte binary uint32 address/length header per block; lengths exclude headers and Big Endian is the default.
|
|
- Treat every Intel HEX address and length operation as checked uint32 arithmetic. Reject overflow, conflicting overlap, malformed control records, excessive records and excessive blocks before allocating result buffers.
|
|
- Treat asynchronous replacement and clearing as race-sensitive: stale Worker, file, image, or key-generation results must never replace current state.
|
|
- Keep IDs synchronized across `shared/tool-catalog.json`, `shared/default-navigation.json`, and `src/tools/registry.ts`.
|
|
- Use the shared UI components and existing responsive styles.
|
|
- Do not edit generated `dist/` directly; rebuild it from source.
|
|
- Do not overwrite or delete `data/navigation.json`.
|
|
- Run `npm run check` after every change. Run `npm audit --audit-level=low` before a release.
|
|
- For UI changes, verify desktop and mobile portrait layouts in a real browser.
|
|
- A release must update all version references and `CHANGELOG.md`, rebuild the delivery ZIP, and regenerate SHA-256.
|