CLAUDE.md · hhyqhh/inno-agent

Sections

1. Repository Layout
2. Common Commands
3. Design Philosophy
4. Runtime Path Resolution
5. Architecture
6. Docker
7. Configuration

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

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Layout

This is an npm workspaces monorepo (Node.js >=20.6.0, ES modules) for **Inno Agent**, a personal learning agent built on the PI SDK.

- `apps/inno-agent/` — backend (CLI + HTTP server), TypeScript, compiles to `dist/`.
- `apps/inno-agent/web/` — frontend (React 19 + Lit + Tailwind 4 + Vite), workspace `inno-agent-web`.
- `electron/` — Electron main process (`main.js` + `loading.html`) for desktop builds.
- `build/` — desktop app icons (`icon.icns`, `icon.png`, `icon.svg`).
- `scripts/` — Electron build hooks (`after-pack.cjs`, `build-mac.sh`), the bundled LibreOffice staging scripts (`prepare-libreoffice.sh` / `prepare-libreoffice.ps1`), the vendored PPTist regeneration script (`prepare-pptist.sh`), and the self-hosted content hub server (`content-hub-server/`).
- `docs/` — screenshots, use-case guides, and `SYSTEM_DEPENDENCIES.md`.
- `runtime/` — local runtime state (config, data, skills); gitignored. Mapped to `INNO_*` env vars.
- `workspace/` — default agent working directory; gitignored.

PI SDK packages (`@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-web-ui`) are pulled from npm.

Key dependencies: `ws` (WebSocket), `node-pty` (PTY terminal), `cron-parser` (scheduler), `@larksuiteoapi/node-sdk` (Feishu), `typebox` (validation), `undici` (HTTP client), `@juicesharp/rpiv-ask-user-question` (bridges agent `ask_user_question` tool calls to the web UI), `@juicesharp/rpiv-todo` (`todo` task-list tool), `pi-web-access` (`fetch_content`/`get_search_content` URL/GitHub/PDF/YouTube extraction), `pi-subagents` (optional subagent support), `pi-sandbox` (optional OS-level sandboxing), `graphology` + `graphology-communities-louvain` (wiki knowledge graph), `yaml` (YAML parsing), `@llamaindex/liteparse` (document parsing).

Tests run with `npm test` (`vitest run`, root script) and also execute in the release CI. The suite is 169 files (1,420 tests), including backend chat-stream/trace persistence, complete literal search and pagination, L3 index migration/concurrency, web search keyboard/cancellation, workspace header controls, navigation history, Electron search IPC coverage, and the LibreOffice engine/UNO-sidecar/office-tools suite (`engine-locator` / `uno-sidecar` / `office-tools` / `univer-xlsx`). Remaining coverage gaps for channels/scheduler/terminal/L1/L3 are tracked in `docs/quality-remediation-plan.md`. The TypeScript build (`npm run build`) remains the primary sanity check. No ESLint or Prettier configuration exists.

When a PR changes the test count, the size of `server.ts`, or other structural facts stated in this file, update this file in the same PR — AI agents read it as ground truth.

### TypeScript configs

Three tsconfig files, each self-contained (no `extends` chain):

- **`tsconfig.base.json`** (repo root) — reference base: `ES2022` target, `Node16` module/resolution, strict mode, `sourceMap`, `declaration` + `declarationMap`, `experimentalDecorators`, `emitDecoratorMetadata`, `resolveJsonModule`, `useDefineForClassFields: false`. Not directly referenced by the other configs but documents the shared settings.
- **`apps/inno-agent/tsconfig.json`** — backend: `ES2022` target, `Node16` module/resolution, strict mode, `outDir: ./dist`, `rootDir: ./src`, `declaration`, `sourceMap`, `types: ["node"]`. Does NOT use `experimentalDecorators` or `emitDecoratorMetadata` (those are only in the root base config). Compiles `src/foo.ts` → `dist/foo.js`. The compiled server entry point is `dist/server.js` and CLI entry is `dist/cli.js`.
- **`apps/inno-agent/web/tsconfig.json`** — frontend: `ESNext` module, `bundler` resolution, `lib` includes DOM/DOM.Iterable, `jsx: "react-jsx"`, `noEmit: true`, `isolatedModules: true`, `experimentalDecorators: true`, `useDefineForClassFields: false` (both needed for Lit decorator syntax in legacy components). TypeScript is only for type-checking during `vite build` — Vite handles the actual bundling.

`tsx` is available as a dev dependency for running TypeScript files directly without compilation (e.g., `npx tsx some-script.ts`).

### Reference docs

- **[README.md](./README.md)** — full project overview, design rationale, features, deployment, contributing.
- **[QUICKSTART.md](./QUICKSTART.md)** — 5-minute setup guide (Chinese) with provider config examples.
- **[ELECTRON_BUILD.md](./ELECTRON_BUILD.md)** — Electron packaging notes (Chinese).
- **[apps/inno-agent/README.md](./apps/inno-agent/README.md)** — backend API route table and project structure (Chinese).
- **[docs/SYSTEM_DEPENDENCIES.md](./docs/SYSTEM_DEPENDENCIES.md)** — full system-level dependency reference (build-time, runtime, Python environment, native modules). Essential for Docker/deployment work.
- **[docs/PERMISSIONS_AND_SANDBOX.md](./docs/PERMISSIONS_AND_SANDBOX.md)** — permission layer (three policy modes, approval cards, deny floor) and sandbox layer (`--sandbox`, filesystem/network policy) explained with configuration details.

## Common Commands

All commands are run from the repo root and use `npm --workspace` under the hood.

```bash
# Build backend + web
npm run build

# Build frontend only
npm --workspace inno-agent-web run build

# Start HTTP server (serves API + web/dist on port 3000)
npm run server -- --home ./runtime --workspace ./workspace --port 3000

# Start CLI (terminal agent, no HTTP)
npm run start -- --home ./runtime --workspace ./workspace

# Sandbox mode (pi-sandbox enabled, isolates agent tool execution)
npm run sandbox -- --home ./runtime --workspace ./workspace
npm run server:sandbox -- --home ./runtime --workspace ./workspace --port 3000

# Dev: run server and Vite dev separately
npm run dev:server      # backend on :3000
npm run web:dev         # Vite on :5173, proxies /api -> :3000

# Watch mode (TypeScript recompile on change)
npm run dev             # `tsc --watch` in apps/inno-agent (backend only, does not rebuild frontend)

# Run a TypeScript file directly without building
npx tsx some-script.ts

# restart-dev.sh orchestration
npm run restart         # full build + dev restart
npm run restart:fast    # skip build, restart only
```

### First-run setup

```bash
mkdir -p runtime/config runtime/data runtime/skills workspace
cp config.example.json runtime/config/config.json
# Edit runtime/config/config.json — set providers[*].apiKey
```

An `.env.example` file is provided at the repo root with default `INNO_*` env var values for local development.

### Dev restart rules

- Changes to `src/server.ts` or backend API → `npm run build` + restart server.
- Changes to `web/vite.config.ts` → restart Vite.
- Changes under `web/src/` → Vite HMR usually handles it.
- If upload/Wiki/proxy behavior misbehaves, fully restart both. Health checks: `curl localhost:3000/health`, `curl localhost:5173/api/wiki/pages`.

### restart-dev.sh

The `restart-dev.sh` script at the repo root orchestrates the full dev lifecycle:

```bash
bash restart-dev.sh              # build + dev mode start both frontend and backend
bash restart-dev.sh --skip-build # skip compilation, restart processes only
bash restart-dev.sh build        # build only, no service startup
bash restart-dev.sh start        # start services without building
bash restart-dev.sh status       # show process health and port status
bash restart-dev.sh logs server  # tail backend logs
bash restart-dev.sh logs web     # tail frontend logs
bash restart-dev.sh smoke        # run health/session/WS smoke tests
bash restart-dev.sh stop         # stop all managed processes
bash restart-dev.sh --help       # list all options
```

Supports `--mode dev|prod`, `--skip-build`, `--sandbox`/`--no-sandbox`, `--port <N>`, `--web-port <N>` (custom Vite dev port), `--tail` (follow server.log after starting). Environment variables: `INNO_MODE`, `INNO_SANDBOX`, `INNO_WEB_PORT`. Equivalent npm shortcuts: `npm run restart` (full), `npm run restart:fast` (skip build).

### Electron desktop builds

```bash
npm run electron              # Run desktop app locally
npm run electron:build        # Package macOS DMG (arm64)
npm run electron:build:win    # Package Windows NSIS + MSI (x64)
```

`electron/main.js` spawns the Node server as a child process (`ELECTRON_RUN_AS_NODE=1`), shows a loading window while polling `/health`, then opens the main window. First launch creates a default config at `~/.inno-agent/config/config.json`.

### Electron build scripts

- **`scripts/after-pack.cjs`** — electron-builder hook that fixes `node-pty`'s `spawn-helper` executable permissions after packaging. Without this, the in-app terminal fails on macOS/Linux. Declared in `package.json`'s `build.afterPack`.
- **`scripts/build-mac.sh`** — local macOS packaging script (alternative to CI). Supports `--bump patch|minor|major` for version increment and `--open` to open the output DMG.
- **`scripts/prepare-pptist.sh`** — regenerates the vendored PPTist bundle (pinned upstream commit + `scripts/patches/pptist-embed.patch` postMessage bridge) staged into `apps/inno-agent/web/public/pptist/` for the preview pane's pptx edit mode. PPTist is AGPL-3.0; see README "Third-party licenses".
- **`scripts/prepare-libreoffice.sh` / `scripts/prepare-libreoffice.ps1`** — stage a bundled LibreOffice into `vendor/libreoffice/{darwin-arm64,win32-x64}/` (gitignored) from the official DMG / MSI administrative extract. Both release workflows run the matching script before packaging, and electron-builder's per-platform `extraResources` copies it to `<resourcesPath>/libreoffice`. At runtime `electron/main.js` exports `INNO_BUNDLED_TOOLS_DIR=process.resourcesPath` (packaged only), and `apps/inno-agent/src/office/engine-locator.ts` resolves `soffice` in order: `INNO_LIBREOFFICE_PATH` env → bundled copy → staged dev copy → system install → PATH. Desktop installers therefore ship with Office document parsing (liteparse) and the office_* agent tools working out of the box; dev/server deployments still need a system LibreOffice.

### CI/CD

GitHub Actions workflows (`.github/workflows/`):
- `release-mac.yml` — macOS Electron DMG builds on ARM64 (`macos-14` runner), triggered by `v*.*.*` tags or workflow_dispatch with optional version override. Has commented-out code signing + notarization block.
- `release-win.yml` — Windows NSIS + MSI builds on x64 (`windows-latest` runner), same trigger and version-override pattern.

## Design Philosophy

Inno Agent is a **personal learning agent** — not a general coding agent. Key stances that shape the codebase:

- **Layered memory, not a flat chat summary.** Learner state (L1), archived knowledge (L2), and recent dialogue (L3) have different lifecycles — each lives in its own layer with explicit boundaries enforced in the system prompt and storage layout.
- **Durable facts go to tools, not replies.** Anything that affects future teaching is written to L1/L2 via tools, so personalization decisions are evidence-driven and traceable.
- **An open, correctable learner model.** The L1 profile is inspectable and editable by the learner; the system prompt forbids unevidenced labels.
- **The PI SDK kernel is never modified.** All learning behavior is added through registered tools and a single extension hook (`createInnoExtension`), keeping the agent runtime upstream-compatible.

## Runtime Path Resolution

Both `cli.ts` and `server.ts` bootstrap through `apps/inno-agent/src/runtime.ts`. This is the single source of truth for where data lives.

Precedence: CLI flag → env var → `~/.inno-agent/...`.

| CLI flag | Env var | Default |
|---|---|---|
| `--home` | `INNO_HOME` | `~/.inno-agent` |
| `--config` | `INNO_CONFIG_FILE` | `<configDir>/config.json` |
| `--config-dir` | `INNO_CONFIG_DIR` | `<home>/config` |
| `--data` / `--data-dir` | `INNO_DATA_DIR` | `<home>/data` |