Files

T

toor cc644c59f6 Phase 008: close the test and CI loop around the migration

Adds the checks that make the constraints from Phase 001-007 mechanical
instead of tribal knowledge, and clears the legacy brand text that was still
reachable at runtime.

New red-line tests:
  - no-legacy-brand mirrors the harness scan under vitest, and asserts its
    allow-list has not drifted from harness-check.mjs
  - hermes-db-readonly classifies every new DatabaseSync call site by
    following the path it opens, and fails if a state.db handle drops
    readOnly. It also pins the one legitimately writable database.
  - i18n-parity compares the raw zh/en locale objects both ways. The
    existing coverage test merged en into zh at import time, so a key
    missing from zh could never fail there.

harness:check gains the four missing gates from the phase brief - retired
package directories, retired package scripts, a single UI library, and the
required root files. Each was verified to fail by mutating the repo.

The online-update channel had hardcoded upstream URLs. It now reads
HERMES_WEB_UI_VERSION_MANIFEST_URL and friends and degrades with a named
error, because a reimplementation has nowhere to pull releases from.

The remaining legacy strings are deliberate and each carries a reason in the
allow-list: the global-agent relay address and the OpenRouter referer are
load-bearing, the socket role identifier is a wire contract, and the pre-rename
DB filenames would orphan existing deployments if changed. AGENTS.md now says
so explicitly, so a future agent does not "clean them up".

Also removes a dead electron mock alias, an i18n exemption that had stopped
exempting anything, and a teardown race in plugins-view.test.ts where a-spin
animation frames outlived the jsdom environment.

Verified self-contained: with reference_code/ moved aside, harness:check,
build, test and test:e2e all pass, so the directory can now be deleted.

2026-10-19 00:23:19 +08:00

3.7 KiB

Raw Blame History

Agent Map

This file is a short map for coding agents. Keep detailed guidance in docs/ and keep this file small enough to fit into every task context.

First Reads

DEVELOPMENT.md - project commands, coding rules, test rules, and PR shape.
ARCHITECTURE.md - package boundaries, data ownership, and runtime flow.
docs/harness/README.md - how this repository is prepared for agent work.
docs/harness/validation.md - which checks to run for each change type.
docs/harness/worktree-runbook.md - isolated local dev and test setup.
docs/harness/pr-review.md - self-review checklist before pushing.

Common Commands

npm ci --ignore-scripts
npm run harness:check
npm run test
npm run test:e2e
npm run build

Use the smallest relevant check while iterating. Before a broad PR, run npm run harness:check, npm run test:coverage, npm run test:e2e, and npm run build.

Code Ownership Map

packages/client/src - Vue 3 client, stores, routes, i18n, API helpers.
packages/server/src - Koa API, Socket.IO, persistence, Hermes integration.
packages/skills - built-in skills injected into the Hermes skills directory.
tests/client, tests/server, tests/shared - Vitest coverage.
tests/e2e - Playwright browser coverage with mocked backend services.
.github/workflows - CI, release, and Docker packaging automation.

Hard Rules

Keep routes thin: put request handling in controllers and reusable behavior in services.
Keep Web UI state under HERMES_WEB_UI_HOME or HERMES_WEBUI_STATE_DIR.
Keep Hermes Agent state separate from Web UI state.
Register local API routes before proxy catch-all routes.
Use structured APIs and argument arrays instead of shell string construction.
Add user-facing strings to every locale file.
Do not mix unrelated refactors into a bug fix.

Red Lines

packages/server/src/services/hermes/agent-bridge/python/ is read-only vendored code.
The /chat-run Socket.IO event contract must not change event names, field names, field types, or emission timing. Adding optional fields is allowed.
Hermes state.db is read-only. Node-side code must never open it; read session history through the bridge's getHistory/getOutput instead.
services/hermes/group-chat/, lib/context-compressor/, and services/hermes/context-engine/ are the chat chain: changes require a docs/chat-chain-changes/<date>-<slug>.md fragment.
packages/desktop and packages/website are removed; do not reintroduce them.
This repo is a reimplementation. A few upstream service addresses are load-bearing and are deliberately kept, each with a whitelist entry in scripts/harness-check.mjs: the global-agent relay (api.hermes-studio.ai), the OpenRouter referer, and the ESP32 purchase link. Do not "clean them up" as legacy brand text — removing them breaks those features. Do not read the relay address as project identity: this deployment is not affiliated with the upstream operator.
The online-update channel (runtime-version-manager.ts) has no default URL. It reads HERMES_WEB_UI_VERSION_MANIFEST_URL / HERMES_WEB_UI_DOWNLOAD_BASE_URL / HERMES_WEB_UI_GITHUB_REPO and degrades with a named error when unset. Do not reintroduce a hardcoded upstream URL.
ArkScope vendor (packages/client/src/vendor/arkscore/) is decorative only: login-page title, Journey graph background, first-load / empty states. Never in chat, forms, tables, or click-dense areas. Decorative layers must be pointer-events: none and carry no information or interaction.

When The Agent Gets Stuck

Improve the harness instead of repeating the same prompt. Add missing docs, tests, logs, scripts, or CI checks so the next agent can see and verify the constraint directly.

3.7 KiB Raw Blame History