toor
8c1ddf415f
Every chat session now runs through the Hermes bridge, so the three chat chains become feature-equivalent instead of three partially-maintained dispatch paths. Keeping the coding-agent and in-house agent runtimes alive meant every bridge change had to be mirrored into two more runtimes that had already drifted. Historical rows are read, not migrated: sessions stored with the retired source normalize to cli on load, workflow graphs naming the retired agents keep loading and run on the bridge, and the visible-source check plus SOURCE_LABELS still recognize the old value so those sessions stay listed. The public surface follows the code: the OpenAPI generator and the MCP chat-run tool schema drop the six retired entry fields so external callers are not told about runtimes that no longer exist. harness-check gains a RETIRED_RUNTIME scan so the residual check is a mechanical gate instead of a manual grep, with the two surviving read-side compat sites recorded with reasons. Refs: docs/phases/phase_003.md
114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
# Architecture
|
|
|
|
hermes-ui is a TypeScript project that ships a browser dashboard and a Koa
|
|
backend around Hermes Agent. It runs on Node.js and talks to Hermes over an
|
|
Agent Bridge (see "Hermes Integration" below).
|
|
|
|
## Package Boundaries
|
|
|
|
| Area | Path | Responsibility |
|
|
| --- | --- | --- |
|
|
| Client | `packages/client/src` | Vue UI, routing, Pinia stores, API wrappers, i18n, browser-visible state. |
|
|
| Server | `packages/server/src` | HTTP API, auth, Socket.IO, SQLite stores, file access, Hermes runtime integration. |
|
|
| Skills | `packages/skills` | Built-in skills injected into the Hermes skills directory. |
|
|
| Tests | `tests` | Vitest unit/integration tests and Playwright browser tests. |
|
|
| CI | `.github/workflows` | Build, e2e, lockfile, Docker, and release automation. |
|
|
|
|
This is not an npm workspaces monorepo. `packages/client` and
|
|
`packages/server` have no `package.json`; their dependencies are declared in the
|
|
root `package.json`.
|
|
|
|
## Request Flow
|
|
|
|
1. The browser loads the Vite-built client from the Koa server.
|
|
2. Client modules call API helpers from `packages/client/src/api`.
|
|
3. Server routes in `packages/server/src/routes` wire HTTP paths to controllers.
|
|
4. Controllers validate request concerns and delegate reusable behavior to services.
|
|
5. Services own side effects: files, SQLite, Hermes profiles, subprocesses, bridges, and credentials.
|
|
6. Long-running chat and group-chat flows use Socket.IO namespaces managed by server services.
|
|
|
|
Keep each layer narrow. Routes should not grow business logic, and client code
|
|
should not duplicate server persistence rules.
|
|
|
|
## State And Data Ownership
|
|
|
|
- Web UI state defaults to `~/.hermes-web-ui` through `config.appHome`.
|
|
- `HERMES_WEB_UI_HOME` and `HERMES_WEBUI_STATE_DIR` override Web UI state location.
|
|
These identifiers are intentionally kept from the 0.6.x line: renaming them would
|
|
break existing deployment scripts and orphan existing data directories.
|
|
- Hermes Agent state lives under Hermes profile directories and must stay distinct
|
|
from Web UI state. Profile isolation is done by injecting `HERMES_HOME` into child
|
|
processes, never by copying directories.
|
|
- Hermes `state.db` is read-only and owned by the Hermes Agent. Node-side code must
|
|
never open it; read session history through the bridge's `getHistory`/`getOutput`.
|
|
- The project's own SQLite store under `packages/server/src/db` is the only writable
|
|
store for sessions, messages, and usage. There is no startup import sync from
|
|
Hermes state.
|
|
- Uploads default to `config.uploadDir`, which is derived from the Web UI home unless `UPLOAD_DIR` is set.
|
|
- Runtime data directories must also live under the Web UI home, not beside built `dist` assets.
|
|
- Profile-scoped Hermes data should use existing profile helpers instead of manually joining paths.
|
|
|
|
## Server Structure
|
|
|
|
- `routes/` registers HTTP and WebSocket entry points.
|
|
- `controllers/` handles request-level behavior.
|
|
- `services/` owns reusable IO, domain behavior, external process calls, and integration logic.
|
|
- `db/` owns SQLite schemas and stores.
|
|
- `middleware/` owns request middleware such as user auth.
|
|
- `shared/` contains cross-server constants and helpers.
|
|
|
|
Architecture rules:
|
|
|
|
- Register local API routes before proxy catch-all routes.
|
|
- Keep auth behavior centralized in `packages/server/src/services/auth.ts`.
|
|
- Prefer `execFile` or `spawn` with argument arrays over shell command strings.
|
|
- All Hermes CLI calls go through `execHermesWithBin`/`spawnHermesWithBin` in
|
|
`services/hermes/hermes-process.ts`.
|
|
- Use structured file and YAML/JSON parsers when editing structured data.
|
|
|
|
## Hermes Integration
|
|
|
|
Chat runs through the Agent Bridge, which is the only supported path:
|
|
|
|
```
|
|
browser --Socket.IO--> Koa/Node server --JSON over Unix socket--> Python child
|
|
└- hermes-agent run_agent.AIAgent
|
|
```
|
|
|
|
- `services/hermes/agent-bridge/python/` is vendored, read-only code. The only
|
|
exception is the `HERMES_DESKTOP` checks in `bridge_runtime.py`, which hide the
|
|
Windows console window for git subprocesses and must stay.
|
|
- `services/hermes/group-chat/`, `lib/context-compressor/`, and
|
|
`services/hermes/context-engine/` form the chat chain. Changes there require a
|
|
`docs/chat-chain-changes/<date>-<slug>.md` fragment.
|
|
- The Hermes CLI is user-installed. Point `HERMES_BIN` at the executable, or let
|
|
the server resolve `hermes` from `PATH`.
|
|
|
|
## Client Structure
|
|
|
|
- `views/` contains route-level screens.
|
|
- `components/` contains reusable UI.
|
|
- `stores/` contains Pinia state.
|
|
- `api/` contains HTTP clients and should use `packages/client/src/api/client.ts`.
|
|
- `i18n/` contains locale messages for user-facing strings. Only `zh` and `en` are supported.
|
|
- `styles/` contains global styling and theme primitives.
|
|
|
|
Frontend rules:
|
|
|
|
- Use Vue 3 Composition API with `<script setup lang="ts">`.
|
|
- Use Arco Design Vue components. Naive UI is being removed; do not add new
|
|
`naive-ui` imports.
|
|
- Add visible text to every locale file.
|
|
- Keep component styles scoped unless the style is intentionally global.
|
|
|
|
## Validation Surface
|
|
|
|
The minimum mechanical harness is:
|
|
|
|
- `npm run harness:check` for repository docs, workflow, and package-script invariants.
|
|
- `npm run test` or focused Vitest tests for local logic.
|
|
- `npm run test:e2e` for browser-visible routing/auth/chat regressions.
|
|
- `npm run build` for type checking and production bundles.
|
|
|
|
See `docs/harness/validation.md` for change-specific commands.
|