212 lines
7.6 KiB
Markdown
212 lines
7.6 KiB
Markdown
# AgentCompany-Rust Native GPUI Rewrite Plan
|
|
|
|
Goal: rebuild AgentCompany as a native Rust + GPUI desktop app that preserves the current Electron product surface, UI/UX structure, and core execution semantics while replacing the entire application stack with Rust crates and a typed Pi Mono sidecar boundary.
|
|
|
|
Architecture: keep the PRD four-layer split intact. UI lives in `crates/app_ui`, page/application state in `crates/app_models`, business entities and rules in `crates/domain`, persistence and sidecar orchestration in `crates/storage`, `crates/runtime`, and `crates/pi_bridge`. Preserve Electron parity by reading the Electron renderer, screenshots, and e2e flows as the truth source for layout and workflow behavior.
|
|
|
|
Tech Stack: Rust 2024, GPUI, rusqlite, anyhow/thiserror, Pi Mono sidecar over typed JSON RPC, cargo fmt/clippy/test.
|
|
|
|
---
|
|
|
|
## Phase 0: Ground truth and guardrails
|
|
|
|
### Task 0.1: Lock the rewrite truth sources into the repo
|
|
Objective: make the migration inputs explicit so implementation never guesses.
|
|
|
|
Files:
|
|
- Create: `docs/reference/electron-parity.md`
|
|
- Reference: `PRD.md`, `../README.md`, `../问题.md`, `../screenshots/*`, `../src/renderer/**/*`, `../tests/e2e/desktop.smoke.spec.ts`
|
|
|
|
Verification:
|
|
- Document section-to-section mapping for onboarding, dashboard, communication, approvals, documents, and settings.
|
|
- Confirm every item in PRD section 5 and 14 has a Rust destination.
|
|
|
|
### Task 0.2: Stabilize the Rust baseline
|
|
Objective: restore and verify the existing Rust workspace before structural changes.
|
|
|
|
Files:
|
|
- Existing workspace only
|
|
|
|
Verification commands:
|
|
- `cargo fmt --check`
|
|
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
|
|
- `cargo test --workspace`
|
|
|
|
Status at plan creation: complete.
|
|
|
|
---
|
|
|
|
## Phase 1: UI shell parity foundation
|
|
|
|
### Task 1.1: Split the monolithic `app_root.rs`
|
|
Objective: move each page renderer into a dedicated module so the UI can grow toward parity without a god file.
|
|
|
|
Files:
|
|
- Modify: `crates/app_ui/src/app_root.rs`
|
|
- Create: `crates/app_ui/src/app_root/sidebar.rs`
|
|
- Create: `crates/app_ui/src/app_root/overview.rs`
|
|
- Create: `crates/app_ui/src/app_root/runs.rs`
|
|
- Create: `crates/app_ui/src/app_root/inbox.rs`
|
|
- Create: `crates/app_ui/src/app_root/messages.rs`
|
|
- Create: `crates/app_ui/src/app_root/approvals.rs`
|
|
- Create: `crates/app_ui/src/app_root/documents.rs`
|
|
- Create: `crates/app_ui/src/app_root/workspaces.rs`
|
|
- Create: `crates/app_ui/src/app_root/settings.rs`
|
|
- Create: `crates/app_ui/src/app_root/onboarding.rs`
|
|
|
|
Verification:
|
|
- `cargo fmt --check`
|
|
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
|
|
- `cargo test --workspace`
|
|
|
|
### Task 1.2: Introduce explicit shell/theme tokens
|
|
Objective: replace ad-hoc colors and spacing with a tokenized shell that matches the Electron visual hierarchy.
|
|
|
|
Files:
|
|
- Create: `crates/app_ui/src/theme.rs`
|
|
- Create: `crates/app_ui/src/shell.rs`
|
|
- Modify: `crates/app_ui/src/lib.rs`
|
|
- Modify: `crates/app_ui/src/app_root.rs`
|
|
|
|
Verification:
|
|
- main shell matches screenshot structure: left sidebar, top title bar, content canvas, onboarding split screen.
|
|
- `cargo fmt --check`
|
|
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
|
|
- `cargo test --workspace`
|
|
|
|
### Task 1.3: Add parity notes per major screen
|
|
Objective: each Rust screen states which Electron screen and screenshot it is matching.
|
|
|
|
Files:
|
|
- Create: `docs/reference/dashboard-parity.md`
|
|
- Create: `docs/reference/onboarding-parity.md`
|
|
- Create: `docs/reference/communication-parity.md`
|
|
- Create: `docs/reference/approvals-parity.md`
|
|
|
|
Verification:
|
|
- Each note names source files and screenshots.
|
|
|
|
---
|
|
|
|
## Phase 2: Data model and storage completion
|
|
|
|
### Task 2.1: Extend domain IDs and typed entities
|
|
Objective: replace stringly-typed cross-domain references with PRD-aligned newtypes and explicit enums.
|
|
|
|
Files:
|
|
- Modify: `crates/domain/src/lib.rs`
|
|
- Modify: `crates/domain/src/models.rs`
|
|
- Modify: `crates/domain/src/enums.rs`
|
|
- Create as needed under `crates/domain/src/`
|
|
|
|
Verification:
|
|
- repository and runtime APIs accept semantic IDs instead of free-form strings where feasible.
|
|
- `cargo test --workspace`
|
|
|
|
### Task 2.2: Expand SQLite schema toward PRD entities
|
|
Objective: support thread state, artifacts, workspace lease state, audit events, and richer approvals.
|
|
|
|
Files:
|
|
- Modify: `crates/storage/src/schema.rs`
|
|
- Modify: `crates/storage/src/store.rs`
|
|
- Create: `migrations/*` when schema versioning is introduced
|
|
- Create tests under `crates/storage/tests/`
|
|
|
|
Verification:
|
|
- migration tests cover schema bootstrap and round-trip persistence for company, run, approval, message, document, workspace, and artifact slices.
|
|
|
|
---
|
|
|
|
## Phase 3: Runtime contract completion
|
|
|
|
### Task 3.1: Expand Pi bridge protocol to PRD contract
|
|
Objective: cover handshake, run lifecycle, tool lifecycle, approvals, steer, follow-up, and compaction events.
|
|
|
|
Files:
|
|
- Modify: `crates/pi_bridge/src/protocol.rs`
|
|
- Modify: `crates/pi_bridge/src/client.rs`
|
|
- Modify: `crates/runtime/src/service.rs`
|
|
- Modify: `crates/runtime/tests/sidecar_contract.rs`
|
|
|
|
Verification:
|
|
- sidecar contract tests assert handshake, start run, tool approval, steer, follow-up, and run finished flow.
|
|
|
|
### Task 3.2: Add runtime projection into storage/app state
|
|
Objective: runtime events must land in durable state and visible UI state.
|
|
|
|
Files:
|
|
- Modify: `crates/runtime/src/lib.rs`
|
|
- Modify: `crates/storage/src/store.rs`
|
|
- Modify: `crates/app_models/src/state.rs`
|
|
- Add tests where needed
|
|
|
|
Verification:
|
|
- a synthetic runtime event sequence updates run status, approvals, messages, and artifacts in one end-to-end test.
|
|
|
|
---
|
|
|
|
## Phase 4: Vertical workflow parity
|
|
|
|
### Task 4.1: Onboarding parity
|
|
Objective: reproduce the Electron onboarding flow, step structure, and persistence semantics.
|
|
|
|
### Task 4.2: Dashboard parity
|
|
Objective: reproduce metrics, active work, and recent activity layout.
|
|
|
|
### Task 4.3: Communication parity
|
|
Objective: reproduce three-column message layout, message detail, and composer flow.
|
|
|
|
### Task 4.4: Approval parity
|
|
Objective: reproduce approval queue/detail/actions and connect decisions to runtime.
|
|
|
|
### Task 4.5: Documents/workspaces parity
|
|
Objective: reproduce document center and workspace/artifact visibility.
|
|
|
|
Verification for each task:
|
|
- UI-visible proof in Rust layout
|
|
- persisted state proof in SQLite
|
|
- runtime behavior proof where applicable
|
|
- automated test proof
|
|
|
|
---
|
|
|
|
## Phase 5: End-to-end verification
|
|
|
|
### Task 5.1: Native smoke harness
|
|
Objective: add a Rust-native smoke path that boots the app against a temp profile and exercises the primary first-run flow.
|
|
|
|
Files:
|
|
- Create: `crates/app/tests/native_smoke.rs` or equivalent supported harness
|
|
- Add any test support modules needed under `crates/app/tests/`
|
|
|
|
Verification:
|
|
- first-run onboarding bootstrap is exercised against a temp profile
|
|
- smoke test is part of `cargo test --workspace`
|
|
|
|
### Task 5.2: Runtime + storage end-to-end flow
|
|
Objective: one test drives onboarding bootstrap, run creation, tool approval, message writeback, and artifact registration through Rust crates.
|
|
|
|
Files:
|
|
- Create: `crates/runtime/tests/runtime_storage_e2e.rs`
|
|
- Modify storage/runtime code as needed
|
|
|
|
Verification:
|
|
- `cargo test --workspace runtime_storage_e2e -- --nocapture`
|
|
|
|
---
|
|
|
|
## Phase 6: Hardening and release readiness
|
|
|
|
### Task 6.1: Cross-platform shell and path abstraction
|
|
### Task 6.2: crash recovery and session restore
|
|
### Task 6.3: packaging/release pipeline
|
|
|
|
Verification baseline:
|
|
- `cargo fmt --check`
|
|
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
|
|
- `cargo test --workspace`
|
|
|
|
---
|
|
|
|
Execution rule: every completed slice must leave the workspace green and in a committable state before the next slice starts.
|