mid/WebTools
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

完善项目文档并修复响应式布局

Browse Source
This commit is contained in:
mid
2026-08-08 18:09:25 +08:00
parent 34503f2638
commit 4e3d7fed85
5 changed files with 261 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+98 -29
View File
@@ -1,36 +1,105 @@
# 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`.
This file is mandatory for AI and coding agents working in this repository. Read `README.zh-CN.md` in full before changing code. It is the authoritative product, behavior, deployment, extension, and release document; `README.md` is a complete English overview.
## 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.
1. Run `git status --short --branch` and preserve all existing tracked and untracked work. Never revert, overwrite, or clean user changes without explicit permission.
2. Read the closest existing tool component, its `src/lib/` implementation, Worker if present, and related tests before editing behavior.
3. Inspect `shared/tool-catalog.json`, `shared/default-navigation.json`, and `src/tools/registry.ts` before adding or removing a tool.
4. Do not commit, create tags, or push unless the user explicitly requests that action in the current conversation. Never place access tokens or credentials in source, Git configuration, documentation, commands committed to the repository, or release artifacts.
5. Make source changes only. Do not edit generated `dist/`; rebuild it with `npm run build`.
Key rules:
## Product identity and non-goals
- 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.
- Web Tools is a self-hosted Vue 3 + TypeScript browser-local tools application with a zero-dependency Node.js static/configuration server.
- The default production port is `9000`. Port `8081` is only the local Vite development proxy target.
- The application is anonymous. Do not add login, accounts, favorites, sponsorship, analytics, telemetry, advertising, CDN assets, or a database.
- Tool inputs, keys, files, images, and results must remain inside the current browser tab. Do not send them to the Node server, a third-party API, or any remote service.
- `/setting` is a fixed, unlisted route for navigation management. It has no authentication and is not a security boundary. Anyone who can access the application can open it and change the globally shared navigation order.
- The server persists only navigation configuration. Preserve `data/navigation.json` and the configured external data directory; writes must remain temporary-file plus atomic-replace operations.
- Multiple users and tabs may use every tool concurrently. Their calculation state must remain independent; only navigation order is globally shared.
## Architecture rules
- `package.json` is the sole authoritative application version.
- `shared/tool-catalog.json` is the authoritative category/tool catalog. `shared/default-navigation.json` defines first-run ordering.
- Each tool is an independent lazy-loaded Vue component under `src/tools/`; register it in `src/tools/registry.ts`.
- Routes and sidebar entries are generated from the registry and catalog. Do not manually add an ordinary tool route to `src/router.ts`.
- Put parsing, encoding, cryptography, validation, and file-generation logic in testable modules under `src/lib/`. Vue components own presentation and state, not algorithm implementations.
- Put expensive file parsing and calculation in `src/workers/`. Workers still run entirely in the browser.
- Prefer browser standard APIs or existing, reviewed dependencies. Do not hand-roll established cryptographic primitives or file parsers.
- Add dependencies only when necessary. Keep the Node server runtime dependency-free unless a requirement cannot reasonably be met with the standard library.
- Define and enforce resource limits for file sizes, record counts, blocks, decoded image dimensions, random output, and rendered syntax tokens. If a limit changes, update implementation constants, tests, and the limits table in `README.zh-CN.md` together.
## Stable tool behavior
- ASCII/Hex uses UTF-8. Hex input accepts continuous text or chunks separated by whitespace, English commas, or Chinese commas, with an optional `0x` prefix on each chunk. Invalid UTF-8 must fail rather than silently replace bytes.
- Base64 supports standard and URL-safe input. Decoded output supports strict UTF-8, continuous Hex, and `0xNN, ...` byte arrays. Reject invalid characters, padding placement, lengths, and non-canonical trailing bits.
- AES-128-CMAC follows RFC 4493. The key is exactly 16 bytes of Hex and accepts continuous input or whitespace/comma/Chinese-comma-separated chunks with optional `0x` prefixes. Hex messages use the same parser.
- CRC supports BIN and multi-block Intel HEX, CRC-8/16/32/64 presets, and custom `Width`, `Poly`, `Init`, `XorOut`, `RefIn`, and `RefOut`. Combined data is ordered by address without filling gaps, and per-block results remain available.
- Firmware Hash accepts Intel HEX and computes SHA-256 and SHA-512. Effective-data mode concatenates sorted blocks without gap filling. Block-header mode prepends exactly two binary uint32 values, `startAddress` and data-only `dataLength`, to every block. Both fields are four bytes; Big Endian is the default; total input is `Header1 || Data1 || Header2 || Data2 ...`. Never hash a textual Hex representation of the header.
- RSA allows 2048, 3072, and 4096-bit keys with public exponent 65537. Prefer Web Crypto; the node-forge fallback must be seeded from `crypto.getRandomValues`. Export public SPKI PEM, private PKCS#8 PEM, and separately copyable N/E continuous Hex or byte arrays.
- Secure random output comes only from `crypto.getRandomValues`, is limited to 1-65,536 bytes, and supports continuous Hex, spaced Hex, and byte arrays. Changing display format must not regenerate bytes.
- JSON/XML formatting, minification, validation, and syntax highlighting stay local. When highlighting limits are exceeded, render the complete result as plain text rather than truncating it.
- PNG/ICO processing stays local and must enforce both compressed-file and decoded-pixel limits before costly rendering or allocation.
## Intel HEX and asynchronous safety
- Treat every address, length, end-address, offset, and allocation calculation as checked uint32 arithmetic. JavaScript bitwise operators are signed 32-bit and must not be used as unchecked address arithmetic.
- Validate record syntax, byte counts, checksums, control-record lengths/addresses, EOF placement, extended addresses, and the `0xFFFFFFFF` boundary.
- Sort records by absolute address, merge contiguous records, deduplicate identical overlaps, and reject conflicting overlaps. Enforce record, block, and effective-byte limits before allocating combined buffers.
- CRC and Firmware Hash may share the reviewed Intel HEX parser but must keep separate calculation logic, Worker protocols, and Vue state.
- File replacement, clear, mode change, option change, repeated generation, and component unmount can invalidate asynchronous work. Terminate obsolete Workers where possible and use monotonically increasing request/version IDs. A stale Worker, file read, image decode, or key-generation result must never replace current state.
- Clear the native file input value after handling a selection so choosing the same file again still emits a change event.
- Worker messages must be correlated to both the active Worker instance and active request ID. Error and completion handlers must ignore stale instances.
## UI contract
- Preserve the application shell: navigation on the left and tool content on the right on desktop; responsive navigation and a vertical content flow on mobile portrait.
- All tools use the shared visual language. Prefer `ToolPage`, `TextEditor`, `ModeTabs`, existing form/action classes, Lucide icons, and `src/styles.css`; do not create a tool-specific theme.
- Keep desktop controls compact. Use stable grid/flex constraints and allow controls to become full-width where appropriate on narrow screens.
- Prevent horizontal page overflow, clipped controls, nested scrolling accidents, text overlap, layout shifts, and unbounded result columns. Long Hex, hashes, filenames, and table cells require explicit wrapping or contained scrolling.
- Version information remains at the bottom of the sidebar and is read from `package.json`. Every page footer displays exactly `Copyright © mid All Rights Reserved.`
- Do not add a visible link to `/setting`, explanatory marketing copy, login UI, favorites, or sponsorship UI.
- For UI work, verify a wide desktop, an intermediate width around 801-1040 px, and mobile portrait around 390 x 844 in a real browser. Check direct routes, refresh, navigation, search, `/setting`, both themes, console errors, and network requests.
## Adding a tool
1. Choose a permanent, unique kebab-case ID. Published IDs must not change because routes and saved navigation depend on them.
2. Add pure logic and normal, invalid, boundary, resource-limit, and known-vector tests.
3. Add one Vue component under `src/tools/` using shared components and responsive styles.
4. Add matching metadata to `shared/tool-catalog.json` and its default position to `shared/default-navigation.json`. Only change navigation `version: 1` for a schema migration, not for a new tool.
5. Register the Lucide icon and lazy component in `src/tools/registry.ts`. Do not add a manual route.
6. Verify that an old saved `navigation.json` retains its order and receives the missing tool after the Node process restarts and navigation is next loaded.
IDs must remain synchronized across the catalog, default navigation, icon map, and component registry. Existing catalog tests enforce this contract.
## Deployment and release
- Supported deployments are Docker and Node.js 22.12.0+ with `web-tools.ps1` on Windows Server. A Windows single EXE is an optional future deliverable and is not currently built or supported.
- Keep production port changes synchronized across `server/index.mjs`, `web-tools.ps1`, `Dockerfile`, `docker-compose.yml`, `.env.example`, deployment tests, and both READMEs where applicable.
- The Windows update flow requires a clean `main` checkout and uses `git pull --ff-only`. Preserve external `C:\ProgramData\WebTools\data` state.
- New catalog data is loaded by the Node process at startup. Rebuilding `dist` alone is insufficient after catalog changes; restart the server and refresh already-open browser pages.
- If a single EXE is later authorized, use Node.js SEA with embedded read-only web/catalog assets and an external writable data directory. Add per-architecture builds, asset-read abstraction, Windows smoke tests, replacement/update instructions, and optional Authenticode signing. Derive EXE version metadata from `package.json`; do not create another manually maintained version source. Do not commit generated executables.
For a release, synchronize these five tracked files:
1. `package.json`
2. `package-lock.json`
3. `docker-compose.yml`
4. `README.zh-CN.md`
5. `CHANGELOG.md`
Use `npm version patch --no-git-tag-version` or the appropriate minor/major form so the project version in `package.json` and the two project metadata entries in `package-lock.json` remain synchronized. Other lockfile `version` fields belong to dependencies. `README.md` intentionally does not hardcode the current version.
Rebuild `dist`, the requested delivery ZIP, optional Docker image tar, and SHA-256 checksums. Generated assets are release outputs and remain ignored by Git. Never include `node_modules`, `.env`, runtime data, credentials, or local logs.
## Required validation and handoff
- After every code or documentation change, run `npm run check` and `git diff --check`.
- Before a release, also run `npm audit --audit-level=low`.
- For server/deployment changes, validate PowerShell syntax and Docker Compose configuration when the required executables are available. State clearly when a platform-specific check could not be run.
- For UI changes, complete the browser matrix in the UI contract. Automated tests and a successful build do not replace visual verification.
- Report changed behavior, important format/compatibility decisions, tests actually run, and any remaining risk. Report artifact paths and SHA-256 only when the task requested artifacts.
- Do not claim a check passed unless it was actually executed in the current worktree.
CHANGELOG.md
+3
View File
@@ -16,12 +16,15 @@
- Intel HEX 解析器增加全部非空记录上限、显式 uint32 地址空间检查和无符号扩展地址运算，拒绝越过 `0xFFFFFFFF` 的数据。
- 固件 Hash 在普通 HTTP 局域网访问时增加本地 SHA-256/SHA-512 回退，不再依赖 `SubtleCrypto` 必须可用。
- 生产服务在监听端口前检查 `dist/index.html`，缺少构建产物时立即给出构建命令，不再启动后按请求重复返回 500。
- 修复固件 Hash 和安全随机数模式选择框宽度过大，以及 801-1040 像素中间宽度下 CRC 参数区可能横向溢出的问题。
### Documentation
- 补充 `dist/index.html` 缺失、Node 进程未重启、浏览器页面未刷新和前台 PowerShell 退出等启动故障排查说明。
- 将 Node、Docker Compose、容器健康检查、Windows 脚本和示例配置的生产默认端口统一为 `9000`。
- 增加通用 `README.md` 入口并强化 `AGENTS.md` 新会话接手流程，便于其他 AI 在不依赖历史对话的情况下继续维护。
- 完善英文项目入口与中文权威文档，补充核心工具行为、异步竞态、版本文件、Windows 单 EXE 评估和发布边界。
- 扩充 `AGENTS.md` 的工具扩展、Intel HEX 安全、响应式 UI、部署发布和 Git 操作约束。
### Verification
README.md
+106 -11
View File
@@ -1,29 +1,124 @@
# Web Tools
Self-hosted browser-local utilities built with Vue 3, TypeScript, and a small Node.js server. Tool inputs and results stay in each browser tab; the server only persists the shared navigation order.
[简体中文](README.zh-CN.md)
Default production address: `http://localhost:9000`
Web Tools is a self-hosted collection of browser-local utilities built with Vue 3, TypeScript, Vite, and a small zero-dependency Node.js server. It supports multiple simultaneous users: text, keys, files, images, and calculation results remain inside each browser tab. The server only persists the navigation order shared by all visitors.
## Documentation
The authoritative application version is the `version` field in `package.json`. The default production address is `http://localhost:9000`.
- Complete Chinese documentation: [README.zh-CN.md](README.zh-CN.md)
- AI/coding-agent instructions: [AGENTS.md](AGENTS.md)
- Release history: [CHANGELOG.md](CHANGELOG.md)
## Included tools
Any AI or coding agent starting in a new conversation must read `AGENTS.md` and `README.zh-CN.md` before editing the project, then inspect the current Git worktree instead of assuming it is clean.
- ASCII/UTF-8 and Hex conversion
- Base64 and Base64 URL encoding/decoding, with UTF-8, continuous Hex, and source-code byte-array output
- AES-128-CMAC (RFC 4493)
- CRC-8/16/32/64 presets and custom parameters for BIN and multi-block Intel HEX files
- Firmware SHA-256/SHA-512 over Intel HEX effective data, optionally with an address/length header for each block
- RSA 2048/3072/4096-bit key-pair generation with PEM, N/E Hex, and byte-array output
- Cryptographically secure random bytes in continuous Hex, spaced Hex, or byte-array form
- JSON formatting, minification, validation, and syntax highlighting
- XML formatting, minification, validation, and syntax highlighting
- PNG to multi-size ICO conversion
## Quick start
## Security and state model
Docker Compose:
- Tool data is processed locally in browser memory and is not sent to the server or a third party.
- There is no login, account, favorites, sponsorship, telemetry, CDN, or database.
- `/setting` is a fixed, deliberately unlisted management route. It is not authentication: anyone who can reach the application can open that URL and change the globally shared navigation order.
- Theme selection is stored in same-origin browser `localStorage`. The only server-side application data is `navigation.json`.
- The application is suitable for a private network, VPN, or a deployment protected by an external access-control layer. Do not treat the hidden settings URL as an Internet-facing security boundary.
See [README.zh-CN.md](README.zh-CN.md) for the exact algorithm contracts, input limits, concurrency behavior, and server security controls.
## Docker deployment
Requirements: Docker Engine 24+ and Docker Compose v2 on Linux AMD64 or ARM64.
```bash
docker compose up -d --build
```
Windows Server after the first build:
Open `http://server-address:9000`. To change the host port, copy `.env.example` to `.env`, set `WEB_TOOLS_PORT`, and start Compose normally. The container always listens on port `9000` internally.
Useful commands:
```bash
docker compose ps
docker compose logs --tail=100 web-tools
docker compose down
```
Navigation settings are stored in the named volume `web-tools-data`. Recreating the container does not remove them; `docker compose down -v` does.
## Windows Server deployment
Requirements: Git, Node.js 22.12.0 or newer, and PowerShell 5.1 or newer. After cloning the repository:
```powershell
Set-Location C:\Services\WebTools
npm.cmd ci --include=dev
npm.cmd run build
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 start
```
See `README.zh-CN.md` for first installation, updates, Windows startup, security boundaries, tool extension rules, tests, and packaging.
The script listens on `0.0.0.0:9000` by default and stores navigation settings in `C:\ProgramData\WebTools\data\navigation.json`. It accepts `-ListenAddress`, `-Port`, and `-DataDir` overrides. It does not create Windows Firewall rules.
To update a clean checkout on the `main` branch, stop the foreground process with `Ctrl+C`, then run:
```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
```
The update action performs a fast-forward-only pull, rebuilds dependencies from `package-lock.json`, creates a production build, and starts the server. Use `-NoStart` when a scheduled task or service manager will restart it separately.
A Windows single-EXE build is not currently shipped. The Node.js plus PowerShell path and Docker are the supported deployment methods. The Chinese documentation describes the design and cost of adding an optional Node.js Single Executable Application release later.
## Local development
Install dependencies with `npm ci`. Development uses two terminals because Vite proxies configuration requests to a separate local Node server. Port `8081` is only this development proxy target, not a production port.
Terminal one on PowerShell:
```powershell
$env:PORT = '8081'
$env:DATA_DIR = (Join-Path (Get-Location) 'data')
node .\server\index.mjs
```
Terminal two:
```bash
npm run dev
```
Full validation:
```bash
npm run check
npm audit --audit-level=low
```
`npm run check` runs the Vitest suite, Vue/TypeScript type checking, and a production build.
## Architecture and extension points
```text
src/components/ shared UI components
src/lib/ testable computation and parsing logic
src/tools/ one lazy-loaded Vue component per tool
src/workers/ browser workers for expensive file operations
server/ static server and navigation configuration API
shared/tool-catalog.json authoritative tool metadata
shared/default-navigation.json first-run navigation order
tests/ unit and server integration tests
```
New tools must keep their computation independent, register the same stable ID in the catalog, default navigation, and lazy-load registry, reuse the shared UI, define resource limits where appropriate, and include normal, invalid, boundary, and known-vector tests. Routes are generated from the tool registry; ordinary tools do not add routes manually.
For the complete extension procedure and AI handoff rules, read [AGENTS.md](AGENTS.md) and [README.zh-CN.md](README.zh-CN.md) before editing. Inspect the Git worktree first and preserve existing changes.
## Documentation
- [README.zh-CN.md](README.zh-CN.md): authoritative product, deployment, behavior, extension, and release documentation
- [AGENTS.md](AGENTS.md): mandatory instructions for AI and coding agents
- [CHANGELOG.md](CHANGELOG.md): release history and verification records
- [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md): third-party licenses
README.zh-CN.md
+48 -8
View File
@@ -1,5 +1,7 @@
# Web Tools
[English](README.md)
一个匿名访问、自托管的浏览器本地工具箱。支持多人同时使用；除全局导航顺序外，文本、密钥、文件、图片和计算结果均只存在于各自浏览器中，不会发送到服务端。
当前应用版本：`0.0.6`。
@@ -53,6 +55,20 @@ CHANGELOG.md 版本变更、修复和验证记录
- `/setting` 是固定但不公开显示的管理入口；项目没有登录、收藏、赞助或用户系统。
- 页面必须保持统一 UI，并兼容桌面端和移动端竖屏。
## 核心功能契约
以下行为属于已经发布的兼容性约束。修改时必须同步实现、页面提示、自动化测试和本文档，不能只调整界面文案。
- ASCII/Hex 工具按 UTF-8 字节转换文本；Hex 输入接受连续形式，或以空白、英文逗号、中文逗号分隔的片段，并允许每个片段使用可选的 `0x` 前缀。无效 UTF-8 字节必须报错，不能静默替换字符。
- Base64 支持标准和 URL-safe 形式；解码结果可显示为严格 UTF-8、连续 Hex 或 `0x48, 0x9F, ...` 字节数组。无效字符、错误填充和非规范编码必须报错。
- AES-128-CMAC 密钥必须恰好为 16 字节。密钥和 Hex 消息接受连续 Hex，或空格、换行、英文/中文逗号分隔，并允许片段使用可选的 `0x` 前缀；计算语义遵循 RFC 4493。
- CRC 支持 BIN 和多 block Intel HEX，提供 CRC-8/16/32/64 预设，并允许自定义 `Width`、`Poly`、`Init`、`XorOut`、`RefIn` 和 `RefOut`。总 CRC 对按地址升序拼接的有效数据计算，不填充地址空洞，同时输出每个 block 的结果。
- 固件 Hash 只接受 Intel HEX，输出 SHA-256 和 SHA-512。“有效数据”与“Block 校验头”模式的确切字节流见“固件 Hash 固定语义”；默认校验头字节序为 Big Endian。
- RSA 只允许 2048、3072、4096 位密钥，公钥指数固定为 65537。优先使用 Web Crypto，必要时使用由 `crypto.getRandomValues` 提供随机种子的 `node-forge` 回退；公钥为 SPKI PEM，私钥为 PKCS#8 PEM，N/E 可分别显示为连续 Hex 或代码字节数组。
- 安全随机数必须来自浏览器 `crypto.getRandomValues`，长度为 1 至 65,536 字节，支持连续 Hex、空格 Hex 和代码字节数组；切换显示格式不得重新生成随机数据。
- JSON/XML 的格式化、压缩和校验均在浏览器本地完成。语法着色超过资源限制时只能降级为完整纯文本，不能截断结果。
- 文件选择、文件更换、清空、模式切换和组件卸载都可能使异步任务失效。旧 Worker、旧图像解码和旧密钥生成结果不得覆盖当前输入或已清空状态。
## 多人使用与状态边界
- 每个浏览器标签页拥有独立的 Vue 组件状态、文件对象、图像对象和 Web Worker。不同用户、浏览器或标签页不会共享工具输入与结果。
@@ -163,6 +179,21 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\web-tools.ps1 update
脚本不会读取、覆盖或删除 `C:\ProgramData\WebTools\data`。PowerShell 窗口关闭后前台服务会停止；如使用 Windows 计划任务，应让任务执行 `web-tools.ps1 start`，更新时停止任务、运行 `web-tools.ps1 update -NoStart`，然后重新启动任务。
### Windows 单 EXE 交付状态
当前版本**不交付 Windows 单 EXE**。正式支持的部署方式仍是 Docker，或 Windows 上的 Node.js、Git 与 `web-tools.ps1`。对于自用 Windows Server，现有脚本更容易检查、更新和排障，因此单 EXE 不是必要条件。
若后续明确需要把程序交付给没有 Node.js 环境的 Windows 用户，建议采用 Node.js Single Executable Application（SEA），不要为本项目引入 Electron。实现时至少需要：
1. 增加专用的 EXE 启动入口，并把生产 `dist/`、工具目录和默认导航配置作为只读资源嵌入。
2. 抽象静态资源读取方式，使 Node 服务既能读取开发时的文件系统，也能读取 EXE 内嵌资源。
3. 增加 SEA 配置、注入工具（通常为 `postject`）、`build:exe` 脚本以及 Windows x64/ARM64 分架构构建。
4. 继续把 `navigation.json` 放在 EXE 外部的可写数据目录，默认使用 `C:\ProgramData\WebTools\data`，升级 EXE 时不得覆盖它。
5. 增加 Windows Server 启动、端口、静态资源、`/setting`、更新替换和杀毒软件兼容性冒烟测试。
6. 正式对外分发时补充 EXE 图标/版本资源，并考虑 Authenticode 代码签名；未签名程序可能触发 SmartScreen 警告。
这项改造对源码体积影响不大，通常只是数十 KB 级的入口、资源适配和构建脚本，并增加少量开发依赖；真正明显的是发布产物。每个架构的 EXE 会包含 Node.js 运行时，常见为约 60-100 MB 未压缩、约 30-60 MB 压缩，具体随 Node 版本和资源大小变化。EXE 和中间产物必须保持在 `.gitignore` 或发布目录中，不提交到 Git，因此仓库不会明显膨胀；增加的主要成本是分架构构建、签名、测试和更新维护。
## 启动故障排查
- `ENOENT ... dist\\index.html`：当前目录只有源码或尚未生成生产前端。先执行 `npm.cmd ci --include=dev` 和 `npm.cmd run build`，再启动服务；直接执行 `node server\\index.mjs` 不会替代构建步骤。
@@ -364,18 +395,27 @@ AI 不应仅修改 `dist/`；必须修改源码并重新构建。不得覆盖或
处理多人访问、文件工具或异步计算时，还必须检查本文档中的“多人使用与状态边界”和“资源限制”，避免重新引入共享状态、旧任务覆盖新输入或无上限解析。
完成任务后至少报告：修改的工具、数据格式选择、测试和构建结果、容器包路径及 SHA-256。涉及 UI 的改动还要进行桌面和移动端浏览器验收。
完成任务后至少报告：修改内容、关键数据格式选择，以及实际执行的测试和构建结果。只有在任务要求制作发布包时，才需要报告容器包/ZIP 路径及 SHA-256。涉及 UI 的改动还要进行桌面、中间宽度和移动端浏览器验收。
## 版本与发布
应用版本的权威来源是 `package.json`。发布新版本时：
应用版本的唯一权威来源是 `package.json`。`package-lock.json` 记录完整依赖树、下载地址和完整性摘要，供 `npm ci` 复现安装；其中项目自身的版本会在文件顶部和 `packages[""]` 中各出现一次，其余 `version` 都是第三方依赖版本，不应手工统一修改。
1. 使用 `npm version patch --no-git-tag-version` 或按兼容性选择 minor/major，使 `package.json` 与 `package-lock.json` 同步。
2. 更新 `docker-compose.yml` 中的镜像标签。
3. 更新本文档中的当前版本和离线镜像文件名。
4. 在 `CHANGELOG.md` 记录用户可见变更、重要修复和验证结果。
5. 运行测试、生产构建和依赖审计。
6. 重新制作源码/容器部署 ZIP，并生成 SHA-256。
使用 `npm version patch --no-git-tag-version`（或按兼容性选择 minor/major）可以同步更新 `package.json` 与 `package-lock.json`。按当前工程结构，一次完整版本发布需要更新以下 5 个已跟踪文件：
1. `package.json`
2. `package-lock.json`
3. `docker-compose.yml` 中的镜像标签
4. `README.zh-CN.md` 中的当前版本和离线镜像文件名
5. `CHANGELOG.md`
`README.md` 不硬编码版本号，而是指向 `package.json`，因此无需为每次版本升级修改。`AppSidebar.vue` 构建时直接读取 `package.json`，无需手工改其中的版本字符串。发布新版本时：
1. 先更新版本号，再同步镜像标签、本文档和 `CHANGELOG.md`。
2. 运行 `npm run check` 和 `npm audit --audit-level=low`。
3. 重新生成未跟踪的 `dist/` 生产构建。
4. 重新制作源码/容器部署 ZIP，以及任务要求的可选 Docker 镜像 tar，并生成 SHA-256。
5. 检查发布包不包含 `node_modules`、运行数据、令牌、`.env` 或其他本机文件。
版本号固定显示在左侧导航底部；版权信息 `Copyright © mid All Rights Reserved.` 固定显示在所有页面底部。第三方许可保留在 `THIRD_PARTY_NOTICES.md`。
src/styles.css
+6 -4
View File
@@ -224,7 +224,6 @@ button { color: inherit; }
.crc-value { color: var(--text) !important; font-family: "SFMono-Regular", Consolas, monospace; font-weight: 600; }
.hash-config { margin-bottom: 14px; display: flex; align-items: flex-end; flex-wrap: wrap; gap: 12px; }
.hash-config .parameter-field { min-width: 270px; }
.hash-config .mode-tabs { width: 100%; }
.hash-results { margin-top: 16px; }
.hash-summary { min-height: 58px; padding: 10px 13px; display: flex; align-items: center; gap: 12px; color: var(--muted); background: var(--accent-soft); border: 1px solid color-mix(in srgb, var(--accent) 24%, var(--border)); border-radius: 7px; font-size: 11px; }
.hash-summary > div { min-width: 0; }
@@ -251,8 +250,7 @@ button { color: inherit; }
.rsa-parameter-format { margin: 0 0 10px; }
.rsa-parameter-grid { display: grid; gap: 14px; }
.rsa-copy-row { min-height: 30px; margin-top: 4px; justify-content: flex-end; }
.random-controls { margin-bottom: 14px; display: grid; grid-template-columns: minmax(120px, 180px) minmax(310px, max-content) auto; gap: 12px; align-items: end; }
.random-format-field .mode-tabs { min-width: 310px; }
.random-controls { margin-bottom: 14px; display: grid; grid-template-columns: minmax(120px, 180px) max-content auto; gap: 12px; align-items: end; }
.random-check { min-height: 34px; white-space: nowrap; }
.setting-page { max-width: 980px; }
@@ -277,6 +275,11 @@ button { color: inherit; }
.row-action:disabled { opacity: .3; cursor: default; }
.save-state { margin-top: 14px; }
@media (max-width: 1040px) {
.crc-config { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.crc-config .preset-field { grid-column: 1 / -1; }
}
@media (max-width: 800px) {
.app-sidebar { position: fixed; inset: 0 auto 0 0; transform: translateX(-100%); transition: transform .18s ease; box-shadow: 14px 0 32px rgba(20, 24, 28, .14); }
.menu-open .app-sidebar { transform: translateX(0); }
@@ -303,7 +306,6 @@ button { color: inherit; }
.topbar > span:first-of-type, .topbar > svg { display: none; }
.mode-tabs { width: 100%; }
.mode-tab { flex: 1; }
.random-format-field .mode-tabs { min-width: 0; }
.compact-field { width: 100%; justify-content: space-between; }
.compact-field select { flex: 1; }
.editor-panel textarea { min-height: 162px; }