From df189c8310fe7903b85ed364ae4bf0e9c05f8768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EB=AF=BC=EC=9E=AC?= Date: Thu, 14 May 2026 00:02:43 +0900 Subject: [PATCH] docs: clarify contributor setup (#1618) Co-authored-by: honor2030 <19909783+honor2030@users.noreply.github.com> --- AGENTS.md | 8 +++---- CLAUDE.md | 6 ++--- CONTRIBUTING.md | 13 +++++++++-- README.md | 10 ++++++++- gitbooks/developing/README.md | 2 +- gitbooks/developing/getting-set-up.md | 32 ++++++++++++++++++++++----- 6 files changed, 54 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f8bd1d5fc..468ce8137 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ **AI-powered assistant for communities — React + Tauri v2 desktop app with a Rust core (JSON-RPC / CLI) and sandboxed QuickJS skills.** -This file orients contributors and coding agents. Authoritative narrative architecture: [`gitbooks/developing/architecture.md`](gitbooks/developing/architecture.md). Frontend layout: [`gitbooks/developing/frontend.md`](gitbooks/developing/frontend.md). Tauri shell: [`gitbooks/developing/tauri-shell.md`](gitbooks/developing/tauri-shell.md). +This file orients contributors and coding agents. Authoritative narrative architecture: [`gitbooks/developing/architecture.md`](gitbooks/developing/architecture.md). Frontend layout: [`gitbooks/developing/architecture/frontend.md`](gitbooks/developing/architecture/frontend.md). Tauri shell: [`gitbooks/developing/architecture/tauri-shell.md`](gitbooks/developing/architecture/tauri-shell.md). --- @@ -292,7 +292,7 @@ Bundled prompts live under **`src/openhuman/agent/prompts/`** at the **repositor Thin desktop host: window management, daemon health bridging, **core process lifecycle** (`core_process`, `CoreProcessHandle`), and **JSON-RPC relay** to the **`openhuman-core`** sidecar (`core_rpc_relay`, `core_rpc`). -Registered IPC commands (see [`gitbooks/developing/tauri-shell.md`](gitbooks/developing/tauri-shell.md)) include **`greet`**, **`write_ai_config_file`**, **`ai_get_config`**, **`ai_refresh_config`**, **`core_rpc_relay`**, **window** commands, and **OpenHuman service / daemon host** helpers (`openhuman_*`). +Registered IPC commands (see [`gitbooks/developing/architecture/tauri-shell.md`](gitbooks/developing/architecture/tauri-shell.md)) include **`greet`**, **`write_ai_config_file`**, **`ai_get_config`**, **`ai_refresh_config`**, **`core_rpc_relay`**, **window** commands, and **OpenHuman service / daemon host** helpers (`openhuman_*`). Deep link plugin is registered where supported; behavior is platform-specific (see platform notes below). @@ -455,7 +455,7 @@ let resp: BillingChargeResponse = request_native_global( ## App theme & design system -**Design intent**: Premium, calm visual language — ocean primary (`#4A83DD`), sage / amber / coral semantic colors, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. Details: [`gitbooks/resources/design-language.md`](gitbooks/resources/design-language.md). +**Design intent**: Premium, calm visual language — ocean primary (`#4A83DD`), sage / amber / coral semantic colors, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. Implementation tokens live in [`app/tailwind.config.js`](app/tailwind.config.js). ## Desktop shell (Tauri) vs application code @@ -522,7 +522,7 @@ Follow this order so behavior is **specified**, **proven in Rust**, **proven ove ## Platform notes -- **macOS deep links**: Often require a built **`.app`** bundle; not only `tauri dev`. See [`docs/telegram-login-desktop.md`](docs/telegram-login-desktop.md) if applicable. +- **macOS deep links**: Often require a built **`.app`** bundle; not only `tauri dev`. - **`window.__TAURI__`**: Not assumed at module load; guard Tauri usage accordingly. - **Core sidecar**: Must be staged/built so `core_rpc` can reach the `openhuman-core` binary (see `scripts/stage-core-sidecar.mjs`). diff --git a/CLAUDE.md b/CLAUDE.md index 11b60ab82..22730541c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ **AI assistant for communities — React + Tauri v2 desktop app with a Rust core (JSON-RPC / CLI).** -Narrative architecture: [`gitbooks/developing/architecture.md`](gitbooks/developing/architecture.md). Frontend: [`gitbooks/developing/frontend.md`](gitbooks/developing/frontend.md). Tauri shell: [`gitbooks/developing/tauri-shell.md`](gitbooks/developing/tauri-shell.md). Coding-harness tool surface: [`gitbooks/developing/coding-harness.md`](gitbooks/developing/coding-harness.md). +Narrative architecture: [`gitbooks/developing/architecture.md`](gitbooks/developing/architecture.md). Frontend: [`gitbooks/developing/architecture/frontend.md`](gitbooks/developing/architecture/frontend.md). Tauri shell: [`gitbooks/developing/architecture/tauri-shell.md`](gitbooks/developing/architecture/tauri-shell.md). Agent-harness tool surface: [`gitbooks/developing/architecture/agent-harness.md`](gitbooks/developing/architecture/agent-harness.md). --- @@ -165,7 +165,7 @@ bash scripts/test-rust-with-mock.sh --test json_rpc_e2e Thin desktop host: window management, daemon health, **core process lifecycle** (`core_process`, `CoreProcessHandle`), **JSON-RPC relay** (`core_rpc_relay`, `core_rpc`). -Registered IPC (see [`gitbooks/developing/tauri-shell.md`](gitbooks/developing/tauri-shell.md)): `greet`, `write_ai_config_file`, `ai_get_config`, `ai_refresh_config`, `core_rpc_relay`, window commands, `openhuman_*` daemon helpers. +Registered IPC (see [`gitbooks/developing/architecture/tauri-shell.md`](gitbooks/developing/architecture/tauri-shell.md)): `greet`, `write_ai_config_file`, `ai_get_config`, `ai_refresh_config`, `core_rpc_relay`, window commands, `openhuman_*` daemon helpers. ### CEF child webviews — no new JS injection @@ -233,7 +233,7 @@ Each domain owns a `bus.rs` with its `EventHandler` impls — e.g. `cron/bus.rs` ## Design -Premium, calm visual language — ocean primary `#4A83DD`, sage / amber / coral semantics, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. See [`gitbooks/resources/design-language.md`](gitbooks/resources/design-language.md). +Premium, calm visual language — ocean primary `#4A83DD`, sage / amber / coral semantics, Inter + Cabinet Grotesk + JetBrains Mono, Tailwind with custom radii/spacing/shadows. Implementation tokens live in [`app/tailwind.config.js`](app/tailwind.config.js). ## Shell vs app code diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 789c9a821..8893abc26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,7 @@ This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDU | Node.js | `>=24.0.0` from [`app/package.json`](app/package.json) | Install the current Node 24 release or newer. | | pnpm | `pnpm@10.10.0` from [`package.json`](package.json) | The repo enforces pnpm via the root `packageManager` field. | | Rust | `1.93.0` from [`rust-toolchain.toml`](rust-toolchain.toml) | Install with `rustup`; `rustfmt` and `clippy` are required components. | +| CMake | Current stable | Required by native Rust dependencies such as Whisper bindings. | | Tauri vendored sources | Git submodules under `app/src-tauri/vendor/` | Required for the CEF-aware Tauri CLI and notification plugin patches. | | macOS tools | Xcode Command Line Tools | Needed for local desktop builds on macOS. | | Linux desktop packages | System GTK/WebKit/AppIndicator build deps | Install the package set Tauri requires for your distro before attempting desktop builds. | @@ -47,6 +48,14 @@ This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDU - **Linux desktop builds** require extra system packages beyond Node/Rust. Follow the distro-specific Tauri dependency list before running desktop commands, then use the OpenHuman scripts below. For deeper platform troubleshooting, see [`gitbooks/developing/getting-set-up.md`](gitbooks/developing/getting-set-up.md). - **Skills development** happens in the separate [`tinyhumansai/openhuman-skills`](https://github.com/tinyhumansai/openhuman-skills) repository. This repo consumes built skill bundles from GitHub or a local override path; it does not vendor the skills source as a submodule. +Example macOS bootstrap with Homebrew: + +```bash +brew install node@24 pnpm rustup-init cmake +rustup toolchain install 1.93.0 --profile minimal +rustup component add rustfmt clippy --toolchain 1.93.0 +``` + ### 2. Clone and install Fork the upstream repository on GitHub first if you plan to submit changes, then clone your fork: @@ -161,8 +170,8 @@ Useful local paths during development: Most contributor-visible configuration and state flows are documented in: - [`gitbooks/developing/getting-set-up.md`](gitbooks/developing/getting-set-up.md) -- [`gitbooks/developing/frontend.md`](gitbooks/developing/frontend.md) -- [`gitbooks/developing/tauri-shell.md`](gitbooks/developing/tauri-shell.md) +- [`gitbooks/developing/architecture/frontend.md`](gitbooks/developing/architecture/frontend.md) +- [`gitbooks/developing/architecture/tauri-shell.md`](gitbooks/developing/architecture/tauri-shell.md) ## Project Layout diff --git a/README.md b/README.md index 1ab687f75..ff5dcf088 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,15 @@ OpenHuman is an open-source agentic assistant designed to integrate with you in - **[Messaging channels](https://tinyhumans.gitbook.io/openhuman/features/integrations#messaging-channels)** and **[privacy & security](https://tinyhumans.gitbook.io/openhuman/features/privacy-and-security)**: inbound/outbound across the channels you already use, with workflow data that stays on device, encrypted locally, treated as yours. -For contributors: Read the [Architecture](https://tinyhumans.gitbook.io/openhuman/developing/architecture) · [Getting Set Up](https://tinyhumans.gitbook.io/openhuman/developing/getting-set-up) · [Cloud Deploy](https://tinyhumans.gitbook.io/openhuman/developing/cloud-deploy) · [`CONTRIBUTING.md`](./CONTRIBUTING.md). +## Contributing from source + +New contributor? Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the fork/PR workflow and local validation commands. The short path is: + +1. Install Git, Node.js 24+, pnpm 10.10.0, Rust 1.93.0 (`rustfmt` + `clippy`), CMake, and the platform desktop build prerequisites. +2. Fork and clone the repo, then run `git submodule update --init --recursive` before `pnpm install` so the vendored Tauri/CEF sources are present. +3. Use `pnpm dev` for web-only UI work, `pnpm --filter openhuman-app dev:app` for the desktop shell, and focused checks such as `pnpm typecheck`, `pnpm format:check`, and `cargo check -p openhuman --lib` before opening a PR. + +Deeper docs: [Architecture](https://tinyhumans.gitbook.io/openhuman/developing/architecture) · [Getting Set Up](https://tinyhumans.gitbook.io/openhuman/developing/getting-set-up) · [Cloud Deploy](./gitbooks/features/cloud-deploy.md). ## Context in minutes, not weeks diff --git a/gitbooks/developing/README.md b/gitbooks/developing/README.md index 8907154e5..b8089beeb 100644 --- a/gitbooks/developing/README.md +++ b/gitbooks/developing/README.md @@ -56,7 +56,7 @@ PRs must clear the **≥ 80% coverage on changed lines** gate. Add tests for new ## Going deeper -* [**Coding Harness**](/broken/pages/RRYmjibvEbtqRSPntgPX). The agent's code-focused tool surface and how to extend it. +* [**Agent Harness**](architecture/agent-harness.md). The agent's code-focused tool surface and how to extend it. * [**Chromium Embedded Framework**](cef.md). How embedded provider webviews work, why they don't run injected JS, and what the per-provider scanners do instead. For features still being built, the [Subconscious Loop](../features/subconscious.md) page covers the background task evaluation system end-to-end. diff --git a/gitbooks/developing/getting-set-up.md b/gitbooks/developing/getting-set-up.md index 54f1f292b..f2eeff77d 100644 --- a/gitbooks/developing/getting-set-up.md +++ b/gitbooks/developing/getting-set-up.md @@ -17,8 +17,20 @@ This guide covers two paths: ## Prerequisites - `git` -- `node` + `pnpm` (see `pnpm-workspace.yaml`) -- Rust toolchain (see `rust-toolchain.toml`) +- Node.js 24 or newer (see `app/package.json`) +- `pnpm@10.10.0` (see the root `package.json` `packageManager` field) +- Rust 1.93.0 through `rustup` with `rustfmt` and `clippy` (see `rust-toolchain.toml`) +- CMake, required by native Rust dependencies +- Git submodules under `app/src-tauri/vendor/`, required for the vendored CEF-aware Tauri CLI +- Platform desktop build tools: Xcode Command Line Tools on macOS, or the Tauri GTK/WebKit/AppIndicator package set on Linux + +macOS Homebrew quick start: + +```bash +brew install node@24 pnpm rustup-init cmake +rustup toolchain install 1.93.0 --profile minimal +rustup component add rustfmt clippy --toolchain 1.93.0 +``` ## Build from source (local compile) @@ -29,24 +41,32 @@ Run from the repository root: git clone https://github.com/tinyhumansai/openhuman.git cd openhuman -# 2) Install JS deps (workspace) +# 2) Fetch vendored Tauri/CEF sources +git submodule update --init --recursive + +# 3) Install JS deps (workspace) pnpm install -# 3) Build Rust core binary +# 4) Build Rust core binary cargo build --manifest-path Cargo.toml --bin openhuman-core -# 4) Stage core sidecar for the desktop app +# 5) Run the desktop staging hook (currently a no-op; kept for script compatibility) cd app pnpm core:stage -# 5) Build desktop app artifacts +# 6) Build desktop app artifacts pnpm build ``` For local development instead of production build: ```bash +# Web-only UI development: run inside app/ after the `cd app` step above pnpm dev + +# Desktop app development with the vendored Tauri/CEF CLI: run from the workspace root +cd .. +pnpm --filter openhuman-app dev:app ``` ## Install latest stable release (macOS/Linux x64)