AGENTS.md · GCWing/OpenBitFun

Sections

1. Quick start
2. Layered Module Index
3. Common commands
4. Global rules
5. Architecture
6. Verification
7. Agent-doc priority

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

[中文](AGENTS-CN.md) | **English**

# AGENTS.md

OpenBitFun is a Rust workspace plus React frontends.

Repository rule: **keep product logic platform-agnostic, then expose it through platform adapters**.

## Quick start

1. Read `README.md` and `CONTRIBUTING.md` before architecture-sensitive changes.
2. Use the primary product loop below for normal development. Surface-specific
   alternatives belong in the nearest app guide.
3. After Rust file changes, prefer `pnpm run fmt:rs` to format only changed or staged `.rs` files. Use `cargo fmt` only when you intentionally want broader formatting coverage.
4. After changes, use the nearest local `AGENTS.md` for the focused verification
   command. The repository-level verification section below only covers
   cross-cutting checks.
5. Workspace Rust dependencies own compatible versions, not broad capability
   unions. Each crate must select the dependency features it actually uses;
   keep test-only features in dev-dependencies and attach feature-gated service
   capabilities to the owning crate feature. Disable third-party defaults in
   `[workspace.dependencies]` when they are not part of every consumer's
   contract; members inherit that policy and add only their needed slices. For
   internal crates whose guarded `default` is empty, do not repeat
   `default-features = false` on every edge. Narrow consumers of an intentional
   compatibility default, such as ACP, must still disable it explicitly.
   Manifests copied into a standalone Docker build context must keep explicit
   versions and default policy because they cannot inherit the workspace root.
   `tokio/full` is forbidden in the root workspace and workspace members.

## Layered Module Index

Dependencies flow top to bottom. This table is the physical crate layout, not
the full conceptual architecture. For Product Surface / Product Assembly /
Product Feature / Agent Kernel / Execution / Extension / Cross-platform Adapter /
Stable Contracts and Security Control Plane boundaries, read
[`docs/architecture/product-architecture.md`](docs/architecture/product-architecture.md).
Keep crate dependencies inside each layer to the smallest set needed.

| # | Layer | Path | Owns | Modules / entries | Layer doc |
|---|---|---|---|---|---|
| 1 | Interfaces and entrypoints | `src/apps/*`, `src/web-ui`, `src/mobile-web`, `OpenBitFun-Installer`, `tests/e2e`, `src/crates/interfaces` | Product hosts, commands, UI entrypoints, protocol interfaces, and cross-surface tests | desktop, CLI, server, relay, Web UI, mobile web, installer, E2E, `acp`, `app-server`, `sdk-host` | nearest local `AGENTS.md`; [interfaces](src/crates/interfaces/AGENTS.md) |
| 2 | Product assembly | `src/crates/assembly` | Compatibility exports, product capability selection, product-full wiring, immutable built-in Agent content, adapter/service registration, and ecosystem-neutral source coordination | `agent-content`, `core`, `external-sources`, `product-capabilities` | [AGENTS.md](src/crates/assembly/AGENTS.md) |
| 3 | Adapters | `src/crates/adapters` | AI/transport/WebDriver protocol adapters, external AI work source adapters (OpenCode/Claude Code/Codex/Zcode), and external-provider translation | `agent-runtime-ipc`, `ai-adapters`, `opencode-adapter`, `claude-code-adapter`, `codex-adapter`, `zcode-adapter`, `static-hook-support`, `transport`, `webdriver` | [AGENTS.md](src/crates/adapters/AGENTS.md) |
| 4 | Services | `src/crates/services` | Reusable OS, filesystem, terminal, MCP, remote, git, watch, process, session persistence primitives, MiniApp runtime IO, and network implementations | `services-core`, `services-integrations`, `computer-use`, `miniapp-market-service`, `relay-service`, `page-function-runtime`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
| 5 | Execution primitives | `src/crates/execution` | Portable Agent Runtime, named-workflow policy, stream, plugin runtime client, typed-service, tool-contract, tool-group, and tool-execution building blocks | `agent-runtime`, `agent-workflows`, `agent-stream`, `tool-contracts`, `plugin-runtime-client`, `runtime-services`, `tool-provider-groups`, `tool-execution` | [AGENTS.md](src/crates/execution/AGENTS.md) |
| 6 | Stable contracts and product domains | `src/crates/contracts` | Shared DTOs, event shapes, runtime ports, and product domain contracts/policies | `core-types`, `events`, `runtime-ports`, `product-domains` | [AGENTS.md](src/crates/contracts/AGENTS.md) |

Boundary rules:

- Interfaces and app entrypoints expose selected product behavior; reusable behavior moves down.
- Assembly wires lower layers and selects product capability facts; it must not implement concrete adapter, OS, or service details.
- Product features assemble user-facing commands, UI contributions, settings, and default policy on top of kernel capabilities; long-running task, scheduler, permission, session/workspace, memory, DFX, hook, and event facts stay in Agent Kernel owners.
- Adapters translate protocols and external-provider shapes; they should not own product capability selection or reusable OS service behavior.
- Services implement reusable concrete OS, process, terminal, MCP, remote, git, filesystem, and MiniApp runtime IO capabilities.
- External systems are boundary resources, not repository layers. Only registered adapters/services/app-local providers should call them; other layers consume ports and stable contracts.
- Execution crates are portable runtime building blocks, not host-specific or delivery-profile owners.
- Contracts stay behavior-light and must not depend upward.


## Common commands

Keep this list to stable repository entry points. Surface- and crate-specific
test commands belong in the nearest local `AGENTS.md` and must not be copied here.

```bash
# Setup and primary product loop
pnpm install
pnpm run desktop:dev               # full hot-reload: Vite HMR + Rust auto-rebuild & restart

# Repository checks
pnpm run fmt:rs                    # format only changed / staged Rust files
pnpm run check:repo-hygiene        # repository content and filename rules
pnpm run check:github-config       # GitHub workflow/configuration rules
pnpm run check:core-boundaries     # Cargo/module ownership boundaries
```

For Web UI, mobile, CLI, Desktop, Installer, packaging, and focused test
commands, use the nearest local guide. The full script registry remains in
[`package.json`](package.json).

## Global rules

### Check for existing bug fixes before editing

OpenBitFun currently releases roughly once a week, so a user report may describe
a released version whose bug is already fixed on `main` or being addressed in an
open PR. **Before changing code for a bug, check both:**

- **Latest `main`:** refresh the upstream `main` ref without disturbing local
  work, then inspect the relevant implementation, tests, and commit history.
  Check the reported version and reproduction conditions when available; base
  the conclusion on code and behavior, not commit titles alone.
- **Open PRs, including drafts:** search by symptoms and affected modules, then
  inspect relevant diffs to establish whether they cover the same root cause
  and scenario. A similar title alone does not establish coverage.

If `main` already contains the fix, report the supporting commit/code and whether
it is released; do not implement it again. If an open PR covers it, link that PR
and build on or coordinate with the existing work; limit new changes to verified
gaps. Record the check result before starting a new fix. If upstream code or PRs
cannot be checked, state that limitation explicitly instead of claiming that no
fix exists.

### Process artifacts

- Do not add or update files under `docs/superpowers/**`. Keep temporary
  planning, design, and implementation-process artifacts local. Move durable
  architecture or feature facts into the existing document for that area, and
  put user-facing guidance in the owning app README.

### Internationalization

- Locale ids, aliases, fallback rules, and surface defaults are owned by
  `src/shared/i18n/contract/locales.json`. Run `pnpm run i18n:generate`
  after editing it.
- Shared stable labels live in
  `src/shared/i18n/resources/shared/<locale>/terms.json`; workflow copy stays
  in the owning product surface.
- Do not import Web UI locale resources into smaller product surfaces such as
  `src/mobile-web` or `OpenBitFun-Installer`. See `docs/architecture/i18n.md`.
- Static self-contained pages may use generated page-scoped shared-term files;
  they must not import Web UI locale catalogs.
- Web UI loads only bootstrap namespaces eagerly; use `useI18n(namespace)` for
  route or feature copy and keep direct `i18nService.t(...)` calls in bootstrap
  namespaces.
- Use shared i18n formatting helpers for user-visible dates, times, and
  numbers instead of direct `Intl.*` or `toLocale*` calls.
- `pnpm run i18n:audit` enforces key/placeholder parity, direct static key
  existence, dynamic key source proofs, literal fallback and locale-format
  no-growth baselines, shared-term/l10n governance baselines, non-blocking
  same-text locale inventory, and the no-hardcoded-CJK source budget.

### Theme and color tokens

- Theme and color-token baselines are ratchet contracts, not editable test
  expectations. Do not make a failing theme audit pass by raising values in
  `scripts/theme-color-governance-baseline*.json`, loosening fixture/assertion
  counts, adding broad allowlist entries, or removing CI audit coverage.
- Lower theme baselines when measured debt is removed. If a change truly needs a
  new color or key, add the smallest owner contract and document why existing
  semantic, component, or specialized-domain tokens cannot cover it.
- For theme, CSS variable, widget payload, mobile, installer, or CLI/TUI color
  changes, run `pnpm run theme:color-audit:all`.

### Logging

Logs must be English-only, with no emojis.

- Frontend: [`src/web-ui/LOGGING.md`](src/web-ui/LOGGING.md)
- Backend: [`src/crates/LOGGING.md`](src/crates/LOGGING.md)

### Tauri commands

- Command names: `snake_case`
- TypeScript may wrap with `camelCase`, but invoke Rust with a structured `request`

```rust
#[tauri::command]
pub async fn your_command(