From 015c6989936a69cc0b290fd57aa0b6020fb08d6f Mon Sep 17 00:00:00 2001
From: ekko <152005280+EKKOLearnAI@users.noreply.github.com>
Date: Fri, 15 May 2026 19:30:12 +0800
Subject: [PATCH] replace claude guide with development guidelines (#767)

---
 CLAUDE.md      | 551 -------------------------------------------------
 DEVELOPMENT.md | 104 ++++++++++
 README.md      |   2 +
 README_zh.md   |   2 +
 4 files changed, 108 insertions(+), 551 deletions(-)
 delete mode 100644 CLAUDE.md
 create mode 100644 DEVELOPMENT.md

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index d8b732d..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,551 +0,0 @@
-# CLAUDE.md — Hermes Web UI Development Guide
-
-## Project Overview
-
-Hermes Web UI is a web dashboard for [Hermes Agent](https://github.com/EKKOLearnAI/hermes-web-ui), a multi-platform AI chat system. It provides session management, scheduled jobs, usage analytics, model configuration, channel management (Telegram, Discord, Slack, WhatsApp, etc.), an integrated terminal, and a streaming chat interface.
-
-The project is designed for **multi-agent extensibility** — Hermes is the first agent integration. All agent-specific code is namespaced under `hermes/` directories, so future agents can be added alongside without conflicts.
-
-**Tech stack:**
-
-- **Frontend:** Vue 3 (Composition API, `<script setup lang="ts">`), Naive UI, Pinia, vue-router (hash history), vue-i18n, SCSS, Vite
-- **Backend:** Koa 2, @koa/router v15+, node-pty (WebSocket terminal), reverse proxy to Hermes gateway
-- **Language:** TypeScript (strict mode), single package (no workspaces)
-
----
-
-## Development Commands
-
-```bash
-npm run dev           # Start both server (nodemon) and client (Vite) concurrently
-npm run dev:client    # Vite dev server only (proxies API to backend)
-npm run dev:server    # nodemon + ts-node for server only
-npm run build         # Type-check (vue-tsc) -> Vite build -> esbuild server bundle
-npm run preview       # Preview production build with Vite
-npm run test          # Run tests (vitest)
-npm run test:watch    # Run tests in watch mode
-npm run test:coverage # Run tests with coverage report
-```
-
-- **Dev port:** 8648 (client Vite dev server proxies `/api`, `/v1`, `/health`, `/upload`, `/webhook` to `http://127.0.0.1:8648`)
-- **Prerequisite:** `hermes` CLI must be installed and on `$PATH` (the server wraps it via `child_process.execFile`)
-
----
-
-## Project Structure
-
-```
-hermes-web-ui/
-├── bin/                          # CLI entry point (bin/hermes-web-ui.mjs)
-├── dist/                         # Build output
-│   ├── client/                   # Vite frontend build
-│   └── server/                   # esbuild server bundle
-├── packages/
-│   ├── client/src/               # Vue 3 frontend
-│   │   ├── api/                  # API layer
-│   │   │   ├── client.ts         # Shared: base request utility (auth, fetch wrapper)
-│   │   │   └── hermes/           # Hermes-specific API modules
-│   │   │       ├── chat.ts       # Gateway proxy: runs, SSE events, models
-│   │   │       ├── jobs.ts       # Gateway proxy: scheduled jobs CRUD
-│   │   │       ├── sessions.ts   # Local BFF: session management (wraps hermes CLI)
-│   │   │       ├── profiles.ts   # Local BFF: profile management (wraps hermes CLI)
-│   │   │       ├── config.ts     # Local BFF: app config, weixin credentials
-│   │   │       ├── logs.ts       # Local BFF: log file listing & reading
-│   │   │       ├── skills.ts     # Local BFF: skills listing, memory CRUD
-│   │   │       ├── gateways.ts   # Local BFF: gateway management
-│   │   │       ├── codex-auth.ts # Local BFF: Codex authentication
-│   │   │       └── system.ts     # Local BFF: health, model config, providers
-│   │   ├── composables/          # Vue composables
-│   │   │   ├── useKeyboard.ts    # Keyboard shortcut composable
-│   │   │   └── useTheme.ts       # Theme management composable
-│   │   ├── components/           # Vue components
-│   │   │   ├── layout/           # Shared: AppSidebar, LanguageSwitch, ModelSelector, ProfileSelector, ThemeSwitch
-│   │   │   └── hermes/           # Hermes-specific components
-│   │   │       ├── chat/         # ChatPanel, ChatInput, MessageList, MessageItem, MarkdownRenderer
-│   │   │       ├── jobs/         # JobCard, JobFormModal, JobsPanel
-│   │   │       ├── models/       # ProviderCard, ProviderFormModal, ProvidersPanel, CodexLoginModal
-│   │   │       ├── profiles/     # ProfileCard, ProfileCreateModal, ProfileImportModal, ProfileRenameModal, ProfilesPanel
-│   │   │       ├── settings/     # AgentSettings, DisplaySettings, MemorySettings, ModelSettings, PlatformCard, PlatformSettings, PrivacySettings, SessionSettings, SettingRow
-│   │   │       ├── skills/       # SkillList, SkillDetail
-│   │   │       └── usage/        # StatCards, DailyTrend, ModelBreakdown
-│   │   ├── i18n/locales/         # en, zh, de, es, fr, ja, ko, pt
-│   │   ├── router/index.ts       # vue-router (hash history)
-│   │   ├── stores/               # Pinia stores
-│   │   │   └── hermes/           # Hermes-specific stores
-│   │   │       ├── app.ts        # App-level state (health, sidebar, models)
-│   │   │       ├── chat.ts       # Chat sessions, messages, streaming
-│   │   │       ├── jobs.ts       # Scheduled jobs CRUD
-│   │   │       ├── models.ts     # Model provider management
-│   │   │       ├── settings.ts   # App configuration
-│   │   │       ├── usage.ts      # Usage statistics
-│   │   │       ├── gateways.ts   # Gateway management
-│   │   │       └── profiles.ts   # Profile management
-│   │   ├── styles/               # global.scss, variables.scss, code-block.scss, theme.ts
-│   │   └── views/                # Page-level components
-│   │       ├── LoginView.vue     # Shared: login page
-│   │       └── hermes/           # Hermes-specific pages
-│   │           ├── ChatView.vue
-│   │           ├── JobsView.vue
-│   │           ├── ModelsView.vue
-│   │           ├── ProfilesView.vue
-│   │           ├── GatewaysView.vue
-│   │           ├── LogsView.vue
-│   │           ├── UsageView.vue
-│   │           ├── SkillsView.vue
-│   │           ├── MemoryView.vue
-│   │           ├── SettingsView.vue
-│   │           ├── ChannelsView.vue
-│   │           └── TerminalView.vue
-│   ├── server/src/               # Koa BFF server
-│   │   ├── controllers/          # Request handlers (thin routes delegate to controllers)
-│   │   │   ├── health.ts         # Health check
-│   │   │   ├── update.ts         # Update check
-│   │   │   ├── upload.ts         # File upload
-│   │   │   ├── webhook.ts        # Incoming webhooks
-│   │   │   └── hermes/           # Hermes-specific controllers
-│   │   │       ├── sessions.ts   # Session CRUD
-│   │   │       ├── profiles.ts   # Profile management
-│   │   │       ├── config.ts     # App config read/write
-│   │   │       ├── gateways.ts   # Gateway management
-│   │   │       ├── codex-auth.ts # Codex authentication
-│   │   │       ├── memory.ts     # Memory CRUD
-│   │   │       ├── models.ts     # Model configuration
-│   │   │       ├── providers.ts  # Provider management
-│   │   │       ├── skills.ts     # Skills listing
-│   │   │       ├── logs.ts       # Log file listing & reading
-│   │   │       └── weixin.ts     # Weixin QR code & credentials
-│   │   ├── routes/               # Route modules
-│   │   │   ├── index.ts          # Route registration (public → auth → protected)
-│   │   │   ├── health.ts         # Health route
-│   │   │   ├── update.ts         # Update route
-│   │   │   ├── upload.ts         # File upload route
-│   │   │   ├── webhook.ts        # Webhook route
-│   │   │   └── hermes/           # Hermes-specific routes (thin wrappers)
-│   │   │       ├── sessions.ts   # Session routes
-│   │   │       ├── profiles.ts   # Profile routes
-│   │   │       ├── config.ts     # Config routes
-│   │   │       ├── gateways.ts   # Gateway routes
-│   │   │       ├── codex-auth.ts # Codex auth routes
-│   │   │       ├── memory.ts     # Memory routes
-│   │   │       ├── models.ts     # Model routes
-│   │   │       ├── providers.ts  # Provider routes
-│   │   │       ├── skills.ts     # Skills routes
-│   │   │       ├── logs.ts       # Log routes
-│   │   │       ├── weixin.ts     # Weixin routes
-│   │   │       ├── terminal.ts   # WebSocket terminal (node-pty)
-│   │   │       ├── proxy.ts      # Reverse proxy routes + middleware
-│   │   │       └── proxy-handler.ts  # Proxy forwarding logic
-│   │   ├── services/             # Business logic
-│   │   │   ├── auth.ts           # Auth middleware & token management
-│   │   │   ├── config.ts         # Server configuration
-│   │   │   ├── config-helpers.ts # Config helper utilities
-│   │   │   ├── logger.ts         # Pino logger
-│   │   │   ├── shutdown.ts       # Graceful shutdown handler
-│   │   │   ├── gateway-bootstrap.ts  # Gateway manager initialization
-│   │   │   └── hermes/           # Hermes-specific services
-│   │   │       ├── hermes-cli.ts # Hermes CLI wrapper (child_process.execFile)
-│   │   │       ├── hermes.ts     # Hermes gateway helpers
-│   │   │       ├── hermes-profile.ts  # Profile management helpers
-│   │   │       ├── gateway-manager.ts # Gateway process management
-│   │   │       └── sessions-db.ts    # SQLite-based session database
-│   │   ├── shared/providers.ts   # Provider model catalogs
-│   │   └── index.ts              # Bootstrap, middleware setup, SPA fallback
-│   └── client/src/shared/        # Frontend shared types (providers.ts)
-├── scripts/                      # Build scripts
-│   ├── build-server.mjs          # esbuild server bundling
-│   └── setup.sh                  # Setup script
-├── tests/                        # Test files
-│   ├── client/                   # Frontend tests
-│   └── server/                   # Backend tests
-├── package.json                  # Single package — no workspaces
-├── vite.config.ts                # root: packages/client, outDir: dist/client
-├── vitest.config.ts              # Vitest test configuration
-└── tsconfig.json                 # Root tsconfig (references for vue-tsc)
-```
-
----
-
-## Naming Conventions
-
-### Multi-Agent Namespacing
-
-All agent-specific code lives under `{agent-name}/` subdirectories. Hermes is the first agent:
-
-| Layer | Shared | Hermes |
-|-------|--------|--------|
-| API | `api/client.ts` | `api/hermes/*.ts` |
-| Components | `components/layout/` | `components/hermes/*/*.vue` |
-| Views | `views/LoginView.vue` | `views/hermes/*.vue` |
-| Stores | _(future: `stores/app.ts`)_ | `stores/hermes/*.ts` |
-| Controllers | `controllers/*.ts` | `controllers/hermes/*.ts` |
-| Routes | `routes/*.ts` | `routes/hermes/*.ts` |
-| Services | `services/*.ts` | `services/hermes/*.ts` |
-| Routes (URL) | `path: '/'` (login) | `path: '/hermes/*'`, `name: 'hermes.*'` |
-| API paths | `/health`, `/upload`, `/webhook` | `/api/hermes/*` |
-
-When adding a new agent, create a new directory at each layer following the same pattern.
-
-### Route Naming
-
-- **Shared routes:** `login`
-- **Agent routes:** `{agent}.{page}` — e.g., `hermes.chat`, `hermes.jobs`, `hermes.profiles`, `hermes.gateways`
-- **Route paths:** `/hermes/{page}` — e.g., `/hermes/chat`, `/hermes/jobs`
-
----
-
-## Frontend Conventions
-
-### Vue Components
-
-All components use `<script setup lang="ts">` with the Composition API:
-
-```vue
-<script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
-import { useI18n } from 'vue-i18n'
-import { NButton, NModal, useMessage } from 'naive-ui'
-import { someApi } from '@/api/hermes/something'
-
-const { t } = useI18n()
-const message = useMessage()
-const loading = ref(false)
-
-async function handleAction() {
-  loading.value = true
-  try {
-    await someApi()
-    message.success(t('common.saved'))
-  } catch {
-    message.error(t('common.saveFailed'))
-  } finally {
-    loading.value = false
-  }
-}
-</script>
-
-<template>
-  <div class="my-component">
-    <NButton :loading="loading" @click="handleAction">{{ t('common.save') }}</NButton>
-  </div>
-</template>
-
-<style scoped lang="scss">
-@use '@/styles/variables' as *;
-
-.my-component {
-  padding: 16px;
-}
-</style>
-```
-
-Key patterns:
-- Import Naive UI components directly from `naive-ui`
-- Use `useMessage()` for toast notifications
-- Use `useI18n()` for translations, access via `t('key.path')`
-- Scoped SCSS with `@use '@/styles/variables' as *`
-
-### Vue Composables
-
-Shared composables live in `packages/client/src/composables/`:
-
-- `useKeyboard.ts` — keyboard shortcut handling
-- `useTheme.ts` — theme management (dark/light mode)
-
-### Pinia Stores
-
-Use setup store syntax (function passed to `defineStore`):
-
-```ts
-import { defineStore } from 'pinia'
-import { ref } from 'vue'
-
-export const useMyStore = defineStore('myStore', () => {
-  const items = ref<Item[]>([])
-  const loading = ref(false)
-
-  async function fetchItems() {
-    loading.value = true
-    try {
-      items.value = await apiCall()
-    } finally {
-      loading.value = false
-    }
-  }
-
-  return { items, loading, fetchItems }
-})
-```
-
-Existing stores in `packages/client/src/stores/hermes/`: `app`, `chat`, `jobs`, `models`, `settings`, `usage`, `gateways`, `profiles`.
-
-### API Layer
-
-Agent-specific API modules live in `api/{agent}/`. The shared base `api/client.ts` provides:
-
-- `request<T>(path, options)` — typed fetch wrapper with automatic `Authorization: Bearer` header and global 401 handling (clears token, redirects to login)
-- `getApiKey()` / `setApiKey()` / `clearApiKey()` — token management via `localStorage`
-- `getBaseUrlValue()` — configurable server URL from `localStorage`
-
-```ts
-// packages/client/src/api/hermes/sessions.ts
-import { request } from '../client'
-
-export async function fetchSessions(source?: string, limit?: number): Promise<SessionSummary[]> {
-  const params = new URLSearchParams()
-  if (source) params.set('source', source)
-  if (limit) params.set('limit', String(limit))
-  const query = params.toString()
-  const res = await request<{ sessions: SessionSummary[] }>(`/api/hermes/sessions${query ? `?${query}` : ''}`)
-  return res.sessions
-}
-```
-
-**API path rules:**
-- Local BFF endpoints: `/api/hermes/{resource}` — handled by Koa routes, call Hermes CLI directly
-- Gateway proxy endpoints: `/api/hermes/v1/*`, `/api/hermes/jobs/*` — forwarded to upstream Hermes gateway
-- Shared endpoints: `/health`, `/upload`, `/webhook` — no agent prefix
-
-### i18n
-
-Eight locales in `packages/client/src/i18n/locales/`: `en`, `zh`, `de`, `es`, `fr`, `ja`, `ko`, `pt`. Flat nested object structure organized by feature section:
-
-```ts
-// en.ts
-export default {
-  chat: {
-    emptyState: 'Start a conversation with Hermes Agent',
-    inputPlaceholder: 'Type a message...',
-    sessions: 'Sessions',
-    // ...
-  },
-  common: {
-    save: 'Save',
-    cancel: 'Cancel',
-    delete: 'Delete',
-    // ...
-  },
-}
-```
-
-When adding new strings, add to all locale files.
-
-### SCSS Styling
-
-- Global variables in `packages/client/src/styles/variables.scss` — import with `@use '@/styles/variables' as *`
-- Naive UI theme overrides in `packages/client/src/styles/theme.ts`
-- Code block styling in `packages/client/src/styles/code-block.scss`
-- Theme: "Pure Ink" (monochrome black/white/gray), no color accent
-- Mobile breakpoint: `$breakpoint-mobile: 768px`
-- Global resets and shared classes in `packages/client/src/styles/global.scss`
-- Component styles are always `<style scoped lang="scss">`
-
-### Router
-
-Hash-based routing (`createWebHashHistory`). All routes use lazy imports. Auth guard in `router.beforeEach` redirects unauthenticated users to `/` (login). Public routes use `meta: { public: true }`.
-
-```ts
-// Agent route example
-{
-  path: '/hermes/chat',
-  name: 'hermes.chat',
-  component: () => import('@/views/hermes/ChatView.vue'),
-}
-```
-
----
-
-## Backend Conventions
-
-### Architecture: Routes + Controllers
-
-The backend follows a **thin-router, fat-controller** pattern:
-
-- **Routes** (`routes/`) — define URL-to-handler mappings, delegate to controller functions
-- **Controllers** (`controllers/`) — contain the actual request handling logic
-- **Services** (`services/`) — reusable business logic, CLI wrappers, utilities
-
-### Koa Server (`packages/server/src/index.ts`)
-
-The server bootstraps in `bootstrap()`:
-1. Creates data/upload directories
-2. Gets auth token
-3. Creates Koa app, initializes gateway manager
-4. Registers CORS, body parser
-5. Registers all routes via `registerRoutes()` (public routes → auth middleware → protected routes)
-6. Registers proxy middleware (catch-all for unmatched `/api/hermes/*` and `/v1/*`)
-7. Serves static SPA files with fallback to `index.html`
-8. Starts server, sets up WebSocket handler
-9. Binds graceful shutdown handler, starts version check
-
-### Route Registration (`packages/server/src/routes/index.ts`)
-
-All routes are registered in a specific order:
-1. **Public routes** (no auth): health, webhook
-2. **Auth middleware** (`requireAuth`)
-3. **Protected routes**: upload, update, session, profile, skill, memory, model, provider, config, log, codex-auth, gateway, weixin, proxy
-
-**Important:** Custom API endpoints handled locally (not proxied) must be registered in `routes/index.ts` **before** `proxyRoutes`. The proxy catch-all matches all `/api/hermes/*` paths.
-
-### Route Modules
-
-Each route module exports a `Router` instance with thin handler delegation:
-
-```ts
-// packages/server/src/routes/hermes/sessions.ts
-import Router from '@koa/router'
-import * as ctrl from '../../controllers/hermes/sessions'
-
-export const sessionRoutes = new Router()
-
-sessionRoutes.get('/api/hermes/sessions', ctrl.list)
-sessionRoutes.get('/api/hermes/sessions/:id', ctrl.get)
-sessionRoutes.delete('/api/hermes/sessions/:id', ctrl.remove)
-sessionRoutes.post('/api/hermes/sessions/:id/rename', ctrl.rename)
-```
-
-**@koa/router v15 syntax** (path-to-regexp v8):
-- Parameters: `:id` (single segment) or `{*path}` (wildcard, matches `/`)
-- No regex groups `(.*)` — use `{*name}` instead
-- No modifiers `:id+` or `:id*` — use `{*name}`
-
-### Reverse Proxy
-
-Unmatched `/api/hermes/*` and `/v1/*` requests are forwarded to the upstream Hermes gateway (`http://127.0.0.1:8642`). Path rewriting in `proxy-handler.ts`:
-
-- `/api/hermes/v1/*` → `/v1/*` (upstream uses `/v1/` prefix)
-- `/api/hermes/*` → `/api/*` (upstream uses `/api/` prefix)
-
-The proxy is implemented as both a route (`proxyRoutes.all('/api/hermes/{*any}', proxy)`) and a middleware (`proxyMiddleware`) registered on the main app to catch any requests that slip through route matching.
-
-### Hermes CLI Wrapper (`packages/server/src/services/hermes/hermes-cli.ts`)
-
-All Hermes interactions go through `child_process.execFile('hermes', [...args])`. Each function wraps a CLI subcommand:
-
-```ts
-export async function listSessions(source?: string, limit?: number): Promise<HermesSession[]> {
-  const { stdout } = await execFileAsync('hermes', ['sessions', 'export', '-'], {
-    maxBuffer: 50 * 1024 * 1024,
-    timeout: 30000,
-  })
-  // Parse newline-delimited JSON output
-}
-```
-
-CLI subcommands wrapped: `sessions export/delete/rename`, `profile list/show/create/delete/rename/use/export/import`, `gateway start/restart/stop`, `logs list/read`, `--version`.
-
-### Auth Middleware (`packages/server/src/services/auth.ts`)
-
-- Token stored in `~/.hermes-web-ui/.token` (auto-generated on first run), or set via `AUTH_TOKEN` env var
-- Auth disabled when `AUTH_DISABLED=1`
-- Applied globally after public routes (health, webhook are registered before auth middleware)
-- For non-API paths (static files), auth is skipped even if no valid token is provided
-- Accepts `Authorization: Bearer <token>` header or `?token=<token>` query param
-
----
-
-## Build System
-
-- **Vite** builds the frontend: root is `packages/client`, output goes to `dist/client`
-- **esbuild** bundles the server via `scripts/build-server.mjs`: output goes to `dist/server`
-- **tsc** type-checks both client (`vue-tsc -b`) and server (`tsc --noEmit`)
-- Path alias: `@` maps to `packages/client/src`
-- Build command: `vue-tsc -b && vite build && tsc --noEmit -p packages/server/tsconfig.json && node scripts/build-server.mjs`
-- TypeScript strict mode enabled for both client and server
-
----
-
-## Key Patterns
-
-### SSE Streaming (Chat)
-
-Chat uses Server-Sent Events via `EventSource`:
-
-```ts
-// packages/client/src/api/hermes/chat.ts
-export function streamRunEvents(runId, onEvent, onDone, onError) {
-  const url = `${baseUrl}/api/hermes/v1/runs/${runId}/events?token=...`
-  const source = new EventSource(url)
-
-  source.onmessage = (e) => {
-    const parsed = JSON.parse(e.data)
-    onEvent(parsed)
-    if (parsed.event === 'run.completed' || parsed.event === 'run.failed') {
-      source.close()
-      onDone()
-    }
-  }
-}
-```
-
-Auth token is passed via query parameter since `EventSource` does not support custom headers.
-
-### WebSocket Terminal
-
-Terminal uses a raw WebSocket at `/api/hermes/terminal` with JSON control messages:
-
-- Client sends: `{ type: "create" }`, `{ type: "switch", sessionId }`, `{ type: "close", sessionId }`, `{ type: "resize", cols, rows }`
-- Client sends raw strings as keyboard input to the active PTY session
-- Server sends raw PTY output strings and JSON messages like `{ type: "created", id, pid, shell }`, `{ type: "exited", id, exitCode }`
-- Uses `node-pty` for pseudo-terminal, `@xterm/xterm` for frontend rendering
-- Auth via `?token=` query parameter on WebSocket upgrade
-
----
-
-## Testing
-
-Tests use **Vitest** with `@vue/test-utils` and `@pinia/testing` for frontend, and `vitest` for backend:
-
-```bash
-npm run test          # Run all tests once
-npm run test:watch    # Watch mode
-npm run test:coverage # With coverage report
-```
-
-Test files live in `tests/client/` and `tests/server/`. Configuration is in root `vitest.config.ts`.
-
----
-
-## Environment Variables
-
-| Variable | Description |
-|---|---|
-| `AUTH_DISABLED` | Set to `1` or `true` to disable auth |
-| `AUTH_TOKEN` | Custom auth token (overrides auto-generated token) |
-| `PORT` | Server listen port (default `8648`) |
-| `UPSTREAM` | Hermes gateway URL (default `http://127.0.0.1:8642`) |
-| `UPLOAD_DIR` | Custom upload directory path (default OS temp dir) |
-| `CORS_ORIGINS` | CORS origin configuration (default `*`) |
-| `HERMES_BIN` | Custom path to hermes CLI binary |
-
----
-
-## Common Tasks
-
-### Add a new Hermes page
-
-1. Create view component in `packages/client/src/views/hermes/MyView.vue`
-2. Add route in `packages/client/src/router/index.ts` with name `hermes.myPage` and path `/hermes/my-page`
-3. Add sidebar entry in `packages/client/src/components/layout/AppSidebar.vue` with `handleNav('hermes.myPage')`
-4. Add i18n keys to all locale files in `packages/client/src/i18n/locales/`
-
-### Add a new Hermes API endpoint
-
-1. Add the controller in `packages/server/src/controllers/hermes/` (request handling logic)
-2. Add the route in `packages/server/src/routes/hermes/` (thin URL-to-controller mapping)
-3. Register the route in `packages/server/src/routes/index.ts` in the protected routes section
-4. If it calls Hermes CLI, add a wrapper function in `packages/server/src/services/hermes/hermes-cli.ts`
-5. Add the frontend API function in `packages/client/src/api/hermes/`
-6. If the endpoint should be proxied to the upstream gateway (not handled locally), ensure the path starts with `/api/hermes/` — the `proxyMiddleware` will catch it automatically
-
-### Add a new Hermes Pinia store
-
-1. Create `packages/client/src/stores/hermes/myFeature.ts` using setup syntax
-2. Export `useMyFeatureStore` from the module
-
-### Add a new agent integration
-
-1. Create `api/{agent}/`, `components/{agent}/`, `views/{agent}/`, `stores/{agent}/` directories
-2. Create `controllers/{agent}/`, `routes/{agent}/`, `services/{agent}/` for agent-specific backend
-3. Add routes with `path: '/{agent}/*'` and `name: '{agent}.*'` in the router
-4. Register routes in `routes/index.ts` following the public → auth → protected pattern
-5. Follow the same patterns as the Hermes integration
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..ddad70c
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,104 @@
+# Development Guidelines
+
+This document defines project-level development rules for Hermes Web UI. It is tool-agnostic and applies to all contributors and coding agents.
+
+## Commands
+
+```bash
+npm install
+npm run dev
+npm run test
+npm run test:coverage
+npm run test:e2e
+npm run build
+```
+
+- `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`.
+
+## 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.
+- Keep component styles scoped with SCSS unless the style is intentionally global.
+- Match existing Naive UI patterns and avoid adding a new 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.
+
+## 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 `codex/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 `[codex] 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`
+```
diff --git a/README.md b/README.md
index 0c326d7..b8128a3 100644
--- a/README.md
+++ b/README.md
@@ -271,6 +271,8 @@ npm run dev
 npm run build   # outputs to dist/
 ```
 
+See [DEVELOPMENT.md](./DEVELOPMENT.md) for project development guidelines.
+
 ## Architecture
 
 ```
diff --git a/README_zh.md b/README_zh.md
index 59ecf7c..3ef7fb9 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -279,6 +279,8 @@ npm run dev
 npm run build   # 构建输出到 dist/
 ```
 
+项目开发规范见：[DEVELOPMENT.md](./DEVELOPMENT.md)。
+
 ## 架构
 
 ```