toor
1e9ea89d86
Import the client, server, skills, tests, and build scripts as the starting point for the rebuild, then trim the surfaces this project does not ship: Electron desktop packaging, the marketing website, and the ESP32 firmware tree. CI keeps the web build, e2e, lockfile, release, and Docker workflows. Rename the package and CLI entry points to hermes-ui, drop the prepare hook so npm ci no longer triggers a build, and drop the removed tsconfig and nodemon references. Rewrite AGENTS.md, ARCHITECTURE.md, DEVELOPMENT.md, and the READMEs so the documented package map and hard rules match this repository. reference_code/ is ignored: it is a read-only snapshot, not an input to the build.
124 lines
5.1 KiB
Markdown
124 lines
5.1 KiB
Markdown
# Development Guidelines
|
|
|
|
This document defines project-level development rules for hermes-ui. It is tool-agnostic and applies to all contributors and coding agents.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js `>=23` (see `engines` in `package.json`).
|
|
- Python with `hermes-agent` installed. The Hermes CLI is not bundled; point
|
|
`HERMES_BIN` at the executable or make `hermes` resolvable from `PATH`.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm ci --ignore-scripts
|
|
npm run dev
|
|
npm run test
|
|
npm run test:coverage
|
|
npm run test:e2e
|
|
npm run build
|
|
```
|
|
|
|
- `npm ci --ignore-scripts` installs exactly what `package-lock.json` pins. Do not upgrade dependencies.
|
|
- `npm run dev` starts the Vite client and Koa server together.
|
|
- `npm run test` runs Vitest unit tests.
|
|
- `npm run test:coverage` is what the Build workflow runs before `npm run build`.
|
|
- `npm run test:e2e` runs Playwright browser tests against a mocked BFF API.
|
|
- `npm run build` type-checks and builds both client and server.
|
|
|
|
## Architecture
|
|
|
|
- Frontend code lives under `packages/client/src`.
|
|
- Server code lives under `packages/server/src`.
|
|
- Hermes-specific client code stays under `hermes` namespaces: API modules, views, stores, and components.
|
|
- Server routes should stay thin. Put request handling in controllers and reusable behavior in services.
|
|
- The chat runtime is Socket.IO based and lives under `packages/server/src/services/hermes/run-chat`.
|
|
- Web UI state lives under `HERMES_WEB_UI_HOME` or `HERMES_WEBUI_STATE_DIR`, defaulting to `~/.hermes-web-ui`.
|
|
- Hermes `state.db` is read-only. Never open it from Node-side code.
|
|
|
|
## Coding Rules
|
|
|
|
- Prefer existing local patterns over new abstractions.
|
|
- Keep changes scoped to the requested behavior.
|
|
- Do not mix unrelated refactors into feature or bugfix commits.
|
|
- Do not reintroduce deprecated compatibility switches without a current caller.
|
|
- Use structured APIs and parsers for structured data instead of ad hoc string edits when possible.
|
|
- Add comments only where they explain non-obvious behavior or constraints.
|
|
|
|
## Frontend Rules
|
|
|
|
- Use Vue 3 Composition API with `<script setup lang="ts">`.
|
|
- Use Pinia setup stores.
|
|
- Use the shared API request helper in `packages/client/src/api/client.ts`.
|
|
- Add user-facing strings to all locale files (`zh.ts` and `en.ts` are the only two).
|
|
- Keep component styles scoped with SCSS unless the style is intentionally global.
|
|
- Use Arco Design Vue components and follow existing Arco patterns. Do not add new `naive-ui` imports
|
|
and do not introduce another UI library.
|
|
|
|
## Server Rules
|
|
|
|
- Register local API routes before proxy catch-all routes.
|
|
- Keep auth behavior centralized in `packages/server/src/services/auth.ts`.
|
|
- Use `config.appHome` for Web UI state paths.
|
|
- Keep Hermes home paths separate from Web UI home paths.
|
|
- Use `getActiveProfileDir()` or related profile helpers for Hermes profile files.
|
|
- Avoid shell string construction for CLI calls; prefer `execFile`/`spawn` with argument arrays,
|
|
routed through `execHermesWithBin`/`spawnHermesWithBin`.
|
|
|
|
## Red Lines
|
|
|
|
- `packages/server/src/services/hermes/agent-bridge/python/` is vendored and read-only. The
|
|
`HERMES_DESKTOP` checks in `bridge_runtime.py` are the one exception and must stay.
|
|
- The `/chat-run` Socket.IO event contract is frozen: no changes to event names, field names,
|
|
field types, or emission timing. Adding optional fields is allowed.
|
|
- Changes under `services/hermes/group-chat/`, `lib/context-compressor/`, or
|
|
`services/hermes/context-engine/` require a `docs/chat-chain-changes/<date>-<slug>.md` fragment.
|
|
|
|
## Testing Rules
|
|
|
|
- Add focused Vitest coverage for server and store logic changes.
|
|
- Add Playwright coverage for browser-visible flows and routing/auth regressions.
|
|
- For frontend browser tests, prefer API/socket mocks over real external services.
|
|
- Before opening a PR, run the smallest relevant tests plus `npm run build`.
|
|
- For broad changes, run:
|
|
|
|
```bash
|
|
npm run test:coverage
|
|
npm run test:e2e
|
|
npm run build
|
|
```
|
|
|
|
## Commit And PR Rules
|
|
|
|
- Branch from `main` for new work.
|
|
- Use short, descriptive branch names such as `fix/login-token` or `feat/group-chat-copy`.
|
|
- Commit only files that belong to the change.
|
|
- Use concise commit messages that describe the change, for example `fix login token storage` or `add group chat clone naming`.
|
|
- Keep commits focused. Do not bundle unrelated cleanup with feature work unless the cleanup is required.
|
|
- Push the branch and open a PR against `main` unless the issue explicitly targets another base.
|
|
- Prefer draft PRs while validation is still running or when the change needs review before merge.
|
|
- Mark a PR ready only after the relevant tests and build pass.
|
|
- Keep PR titles concrete and scoped, for example `make Web UI state directory configurable`.
|
|
- Link issues in the PR body with `Closes #123`, `Fixes #123`, or `Refs #123` as appropriate.
|
|
- PR descriptions should include:
|
|
- what changed
|
|
- why it changed
|
|
- user or developer impact
|
|
- validation commands run
|
|
- known limitations or follow-up work, if any
|
|
- Do not overwrite or revert unrelated user changes.
|
|
|
|
Use this PR body shape by default:
|
|
|
|
```md
|
|
## Summary
|
|
- ...
|
|
- ...
|
|
|
|
Closes #123
|
|
|
|
## Validation
|
|
- `npm run test:coverage`
|
|
- `npm run build`
|
|
```
|