140 lines
6.8 KiB
Markdown
140 lines
6.8 KiB
Markdown
# GoodBuddy Agent Guide
|
|
|
|
## Scope
|
|
|
|
These instructions apply to the entire repository.
|
|
|
|
GoodBuddy is a secure, cross-platform Electron desktop assistant. It uses
|
|
Electron, React, TypeScript, Vite, Vitest, and SQLite. User-facing copy is
|
|
primarily Simplified Chinese.
|
|
|
|
## Architecture
|
|
|
|
- `src/main`: privileged Electron main process, runtimes, persistence, IPC,
|
|
knowledge, automation, and OS integration.
|
|
- `src/preload`: the narrow, typed bridge exposed to the renderer.
|
|
- `src/shared`: schemas, contracts, presets, and IPC channel definitions shared
|
|
across process boundaries.
|
|
- `resources/skills`: bundled skills.
|
|
- `build`: packaging scripts and icons.
|
|
- `out` and `dist`: generated output. Change source files instead.
|
|
|
|
Keep Electron security boundaries intact:
|
|
|
|
- Preserve context isolation and sandboxing.
|
|
- Never enable renderer Node integration.
|
|
- Validate IPC input with shared Zod schemas and verify trusted senders.
|
|
- Expose only explicit preload methods. Do not pass raw Electron APIs.
|
|
- Keep API keys in the main process and encrypted settings store.
|
|
|
|
## Runtime Behavior
|
|
|
|
- Ask and Plan modes must remain read-only at the runtime boundary.
|
|
- Execute mode may use tools only through the existing approval controls.
|
|
- Preserve cancellation, timeout, bounded-output, and shutdown behavior.
|
|
- Treat OpenCode and Continue as untrusted child runtimes. Preserve environment
|
|
allowlists, sandbox checks, and per-tool approval enforcement.
|
|
- A successful image-model configuration check does not prove generation works.
|
|
Only an actual generation request verifies the provider path.
|
|
- Do not fetch provider-returned image URLs. Accept and validate bounded inline
|
|
image data, then persist it as an artifact in the main process.
|
|
|
|
## Data and Compatibility
|
|
|
|
- Preserve existing user data and migrations.
|
|
- Do not weaken SQLite transaction, lifecycle, deduplication, or cleanup logic.
|
|
- Treat user workspaces and untracked files as user-owned.
|
|
- Keep Windows, macOS, Linux x64, and Linux arm64 behavior in mind.
|
|
- Do not hard-code machine-specific paths, credentials, or provider endpoints.
|
|
|
|
## Implementation Conventions
|
|
|
|
- Follow surrounding TypeScript and React patterns.
|
|
- Reuse installed libraries and shared contracts before adding dependencies.
|
|
- Keep changes focused. Do not add unrelated refactors or documentation.
|
|
- Add or update focused tests for behavioral changes and regressions.
|
|
- Avoid broad catches that erase HTTP status, cancellation, or provider error
|
|
context.
|
|
- Keep UI accessible with labels, keyboard behavior, semantic roles, and visible
|
|
focus states.
|
|
|
|
## UI Consistency
|
|
|
|
- Reuse the shared `PageTabs` and `SegmentedControl` primitives instead of
|
|
creating page-specific tab or toggle styles. A semantic tab set may use the
|
|
shared segmented visual variant, but it must retain `tablist`, `tab`,
|
|
`tabpanel`, `aria-selected`, roving focus, and arrow-key behavior.
|
|
- Use the bundled `Inter Variable` and `Noto Sans SC Variable` UI fonts through
|
|
the shared typography tokens. Do not add remote font requests or page-local
|
|
font stacks. Keep redistributed font licenses in packaged resources and
|
|
retain system fallbacks for startup and unsupported glyphs.
|
|
- Route transient success and informational feedback, plus asynchronous errors
|
|
that are not tied to one field, through the application notification
|
|
viewport. Do not render page-local copies of the same notification pattern.
|
|
- Keep inline feedback only when it must remain attached to its context, such
|
|
as field validation, destructive confirmation, operation progress, a
|
|
blocking page state, or an error with an immediate local recovery action.
|
|
- Do not show the same event both inline and as an application notification.
|
|
Preserve user input and actionable error context when an operation fails.
|
|
|
|
## Release Packaging
|
|
|
|
- `.github/workflows/packages.yml` is the canonical cross-platform packaging
|
|
workflow. It validates and builds `out` once, then packages on six native
|
|
runners: Windows, macOS, and Linux, each for x64 and arm64.
|
|
- Run the unified packager with
|
|
`npm run release:package -- --platform <platform> --arch <arch>`. It only
|
|
packages for the native host and writes to
|
|
`dist/release/<platform>-<arch>`.
|
|
- Default deliverables are NSIS and portable ZIP for Windows, DMG and ZIP for
|
|
macOS, and AppImage and DEB for Linux. Every target includes
|
|
`release-manifest.json` with SHA-256 hashes.
|
|
- `build/build-release.cjs` verifies the unpacked application, `app.asar`,
|
|
bundled Continue and OpenCode runtimes, executable architecture, and package
|
|
signatures before atomically replacing a release directory.
|
|
- Keep electron-builder invocations on `--publish never`. Main-branch builds
|
|
run validation and build the production bundle without running the native
|
|
package matrix. Manual builds upload 30-day GitHub Actions artifacts.
|
|
Version-tag builds verify and aggregate packages before publishing GitHub
|
|
Release assets. Signing and macOS notarization are not configured.
|
|
- Keep `ELECTRON_CACHE` and `ELECTRON_BUILDER_CACHE` under
|
|
`${{ runner.temp }}` in step-level workflow contexts. A cache beneath the
|
|
repository inherits the root `"type": "module"` and breaks electron-builder's
|
|
CommonJS macOS icon tool.
|
|
- Tag builds must use `v${package.version}`. The workflow also supports manual
|
|
dispatch and main-branch changes to release tooling.
|
|
- Every push that updates the `github` remote is a release push. Before pushing,
|
|
verify that `package.json` and `package-lock.json` contain the same release
|
|
version, create `v${package.version}` at the exact commit being pushed, and
|
|
push that tag so the native package matrix and GitHub Release run.
|
|
- Never move or reuse an existing release tag. If `v${package.version}` already
|
|
exists locally or on a remote at another commit, increment the package
|
|
version and create a new matching tag before pushing.
|
|
- Verified baseline on 2026-08-04: commit `2f54938`, GitHub Actions run
|
|
`30893805567` succeeded for validation and all six package targets, producing
|
|
six release artifacts plus the shared production bundle.
|
|
|
|
## Validation
|
|
|
|
Run all validators after source changes:
|
|
|
|
```text
|
|
npm test
|
|
npm run typecheck
|
|
npm run lint
|
|
```
|
|
|
|
Run `npm run build` for production build changes. Use `npm run portable` only
|
|
when a current Windows portable package is requested. Gated runtime tests may
|
|
make paid or external calls, so run them only with explicit authorization.
|
|
|
|
Before committing or pushing, inspect `git status`, `git diff`, and
|
|
`git diff --cached`. Do not commit secrets, local databases, logs, generated
|
|
credentials, or private user artifacts.
|
|
|
|
This repository has two synchronized remotes, `origin` and `github`. Unless the
|
|
user explicitly names a remote, every requested push must update the current
|
|
branch on both remotes. Any push that includes `github` must also push the
|
|
required `v${package.version}` release tag to every remote receiving the branch
|
|
update. Verify all updated branch and tag refs after pushing.
|