AGENTS.md · netease-youdao/LobsterAI

Sections

1. Instruction Scope
2. Project Snapshot
3. Commands
4. Testing
5. Quality Gates
6. OpenClaw Integration
7. Architecture Map
8. Data Model
9. OpenClaw State, Workspaces, And Memory
10. Logs
11. Coding Style
12. Legacy Debt And Large Files
13. String Constants
14. Internationalization
15. Artifacts
16. IM, Agents, MCP, And Scheduled Tasks
17. Branches, Commits, And PRs
18. Practical Guidance

First lines (shown under the repo's MIT license)

# AGENTS.md

This file gives coding agents the current working model for this repository.
Treat source code and `package.json` as the authority when something here
appears stale.

## Instruction Scope

This root `AGENTS.md` is repository-level guidance for LobsterAI. Codex may also
load more specific `AGENTS.md` or `AGENTS.override.md` files from subdirectories
when the current working directory is inside those subtrees. More specific
instructions override broader ones.

Do not treat generated runtime workspaces, bundled OpenClaw output, or old
Claude memory notes as authoritative project instructions. Use them only as
historical context and verify against the current source.

## Project Snapshot

LobsterAI is an Electron + React desktop application. Its core user-facing
product is a desktop agent experience that can work with local projects,
files, browser previews, IM channels, skills, MCP servers, scheduled tasks,
and rich artifacts.

### Cowork vs OpenClaw

`Cowork` is LobsterAI's product/session layer. The name is historical: it
started as a Claude Code-like in-house coding assistant, but in the current
codebase it means the LobsterAI layer that owns sessions, messages,
permissions, UI state, local persistence, context usage, artifacts, and IPC
contracts.

`OpenClaw` is the only agent runtime/gateway. `CoworkAgentEngine` is currently
`'openclaw'` only. Legacy names such as `cowork:*` IPC channels,
`claude_session_id`, and some "cowork" filenames are compatibility/history
names, not evidence of another active runtime.

Do not reintroduce or design around `yd_cowork`; it has been removed as a
runtime. If old docs mention it as switchable, verify against current source
before acting.

## Commands

```bash
# First development run: build/sync the pinned OpenClaw runtime, then start app
npm run electron:dev:openclaw

# Daily development after runtime exists: Vite on port 5175 + Electron
npm run electron:dev

# Production renderer bundle
npm run build

# Electron main/preload TypeScript build
npm run compile:electron

# Full ESLint across src; may fail on existing legacy debt
npm run lint

# CI-equivalent lint for touched TypeScript files
npx eslint --ext ts,tsx --report-unused-disable-directives --max-warnings 0 <files>

# Official test entry used by GitHub CI
npm test

# Filter Vitest tests
npm test -- logger
npm test -- cowork

# Package for distribution
npm run dist:mac
npm run dist:win
npm run dist:linux

# Windows installer gate (runs automatically at the start of dist:win and the
# dist:win:web stub pass): re-applies patches/app-builder-lib+*.patch and runs
# the installer contract tests against node_modules. If it fails, run `npm ci`;
# never ship an installer from a tree where it fails.
npm run verify:installer-patches

# Build current-platform OpenClaw runtime manually
npm run openclaw:runtime:host
```

Requirements:
- Node.js `>=24.15.0 <25`.
- Windows builds may need bundled/portable Git setup: `npm run setup:mingit`.
- Windows packaging also sets up the Python runtime via
  `npm run setup:python-runtime`.

OpenClaw environment variables:
- `OPENCLAW_SRC`: override the OpenClaw source checkout path. Default is
  `../openclaw` relative to this repo.
- `OPENCLAW_SKIP_ENSURE=1`: skip automatic OpenClaw tag checkout. Use this only
  when intentionally developing OpenClaw locally.
- `OPENCLAW_FORCE_BUILD=1`: force runtime rebuild where supported by scripts.

## Testing

The current official test path is Vitest:
- `package.json` defines `npm test` as `vitest run`.
- `vitest.config.ts` includes `src/**/*.test.ts` and `tests/**/*.test.ts`.
- GitHub CI runs `npm test`.

Prefer new tests as `.test.ts` files colocated with the source they cover.
Import from Vitest:

```ts
import { describe, expect, test } from 'vitest';
```

There are legacy `tests/*.test.mjs` files that use Node's built-in
`node:test`. They are not part of the default `npm test` run. Only run them
explicitly, e.g. `node --test tests/<file>.test.mjs`, when touching that
legacy coverage.

Avoid importing Electron-only APIs such as `electron-log` directly in tests.
Inline or extract pure logic instead.

For UI/Electron behavior, manually validate with `npm run electron:dev` or
`npm run electron:dev:openclaw` when the OpenClaw runtime is involved.

## Quality Gates

GitHub CI lints changed TypeScript files only. The repository has existing
legacy lint debt; do not attempt a broad lint cleanup unless the user explicitly
asks for it.

When adding or modifying TypeScript/TSX files, leave every touched file free of
ESLint errors and warnings under the same rules CI uses:

```bash
npx eslint --ext ts,tsx --report-unused-disable-directives --max-warnings 0 <files>
```

If full `npm run lint` fails because of unrelated legacy files, report that
clearly and include the changed-file lint result. Do not use broad
`eslint-disable` comments to bypass new issues; use narrow disables only when
there is a specific technical reason.

Verification expectations:
- Docs-only changes: no test run is required; state that tests were not run
  because only documentation changed.
- Renderer/UI changes: run relevant Vitest coverage when available and manually
  validate with `npm run electron:dev` for behavior that tests cannot cover.
- Main process, IPC, runtime, or preload changes: run targeted tests plus
  `npm run compile:electron` or `npm run build` as appropriate.
- OpenClaw integration changes: verify runtime startup, config sync, gateway
  behavior, and relevant logs.
- Before handing off, review the diff for unrelated churn, risky broad
  refactors, generated files, and user-visible string/i18n mistakes.

## OpenClaw Integration

The pinned OpenClaw version and plugin list live in `package.json` under
`openclaw`. The current runtime is built under `vendor/openclaw-runtime/`;
`vendor/openclaw-runtime/current` points to the platform runtime. Packaged apps
bundle the runtime under `Resources/cfmind`.

Main integration points: