AstrBot-Desktop/docs/implementation-plan.md
YokiiroBW 73693b9909
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
docs(p02): start dual connection phase
2026-07-19 21:06:24 +08:00

7.1 KiB

Implementation Plan

P00 Bootstrap (completed)

Objective

Establish a reproducible Tauri 2 + React + TypeScript + Rust baseline and complete the high-risk technical Spikes required before formal feature development.

Ordered work

  1. Normalize repository documents and Git metadata on main.
  2. Verify Forgejo is empty before the first main push; never overwrite remote history.
  3. Create feat/p00-bootstrap from the pushed main baseline.
  4. Establish the Tauri 2 application and typed frontend-to-Rust IPC.
  5. Implement two independent REST/SSE clients and a dual-instance Mock Gateway.
  6. Verify Windows secure credential CRUD without exposing secret values to React or logs.
  7. Verify bounded Windows diagnostics: foreground window, UI Automation, selected-window capture, process information, event logs, ports, network targets, authorized log tails, configuration parsing, and redaction.
  8. Verify NAS transactions only in a dedicated generated fixture directory: dry run, temporary copy, size/hash verification, atomic commit, conflict handling, interruption recovery, and source preservation.
  9. Define protocol schemas and capability negotiation types.
  10. Add frontend, Rust, integration, and Forgejo CI checks.
  11. Run and record all checks, commit by independently verifiable increments, and push the feature branch without merging main.

Safety gates

  • No arbitrary command execution is exposed by product code.
  • No real credential is used in fixtures, logs, snapshots, or commits.
  • No NAS Spike touches an existing user file or directory.
  • No remote branch is changed until git ls-remote succeeds and remote history is reviewed.
  • No test or build is marked successful without captured execution results.

Current handoff status

  • Rust/MSVC/Tauri are verified and no longer block local work.
  • Git Credential Manager reauthentication succeeded and the non-forced HTTP push created the remote main baseline at 0d12b94.
  • Forgejo PR #1 merged P00 into main at b3420e4; development now continues on feat/p01-foundation.
  • The configured SSH fetch endpoint still refuses connections and the LAN SSH endpoint rejects the available key, but the approved HTTP push URL is operational.
  • Forgejo runner labels/jobs remain unverified, so the committed workflow is not claimed successful.
  • Real UNC execution still requires a user-authorized disposable fixture.

P01 Foundation (completed)

Objective

Turn the P00 Spike skeleton into a durable application foundation. Under the project owner's option A decision, P01 includes basic non-sensitive Profile metadata CRUD while P02 retains all slot and runtime connection behavior.

Ordered work

  1. Initialize a persistent SQLite database in the Tauri application-data directory.
  2. Apply versioned, transactional, idempotent migrations and refuse unknown future schema versions.
  3. Validate Rust-to-TypeScript bootstrap payloads at runtime.
  4. Ensure tracing output passes through the shared redaction rules before it reaches a writer.
  5. Add SQLite schema v2 for canonical non-sensitive ConnectionProfile metadata.
  6. Add bounded Tauri list/create/update/delete commands that generate IDs and timestamps in Rust.
  7. Reject secret values, URL credentials, query-string credentials, unknown IPC fields, and implicit insecure HTTP.
  8. Add strict frontend Profile Schemas and a basic management UI without Token/password/API Key inputs.
  9. Test five saved Profiles, CRUD, persistent reopen, v1-to-v2 migration, future-version rejection, and browser fallback.
  10. Re-verify tray, single-instance, explicit exit, frontend, Rust, E2E, development startup, Schema export, and production build behavior.
  11. Record the decision in PD-0008 and ADR-0004, then commit and push the verified branch normally.

P01 boundary

  • Included: durable application database, schema migration, redacted logging, validated bootstrap IPC, basic Profile metadata CRUD, basic Profile management UI, tray, single-instance, and build/test foundations.
  • Excluded: slot assignment, active REST/SSE connections, auto-connect behavior, Profile switching protection, duplicate server_instance_id handling, and formal credential enrollment.

Verification status

  • Frontend formatting, ESLint, TypeScript, 3 Vitest tests, and Vite production build passed.
  • Playwright Chromium passed 1/1.
  • Rust fmt, Clippy with warnings denied, tests, and check passed.
  • Rust test suite passed 50 normal tests; 2 explicit manual tests remained ignored.
  • Protocol Schema export completed without drift.
  • Real Tauri development startup reached the Windows executable and was then deliberately terminated.
  • Windows release and NSIS bundling passed.
  • Forgejo CI remains unverified because a compatible runner/jobs endpoint is unavailable.

P02 Dual Connections (active)

Objective

Add durable companion and operations slot assignment, then build two independent Rust-owned REST/SSE runtimes without weakening the P01 credential and profile boundaries.

Ordered work

  1. Persist the two fixed connection slots and enforce that one Profile cannot occupy both slots.
  2. Add bounded slot list/assign/clear IPC and a minimal settings UI for slot selection.
  3. Add auto-connect validation: at most two Profiles, one per slot, with no duplicate Profile assignment.
  4. Add an operations-switch guard that blocks Profile changes while an operations task is active.
  5. Add duplicate server_instance_id detection and surface a warning without silently merging Profile identity.
  6. Define the production credential enrollment/update/delete lifecycle entirely in Rust, with opaque references in SQLite and no secret values returned to React.
  7. Review the provisional Gateway contract before enabling real configured connections; keep real AstrBot compatibility explicitly unclaimed until the server contract is available.
  8. Implement independent REST discovery/authentication and SSE runtimes, per-Profile cancellation, replay cursors, de-duplication, retry state, and error state.
  9. Integrate the existing dual-instance Mock Gateway and verify that one instance failure or auth expiry does not affect the other.
  10. Add frontend/Rust/integration coverage, update protocol and progress documents, run the full stage checks, and push the branch normally without merging main.

Safety gates

  • Slot work must not accept or expose Token, password, API Key, Cookie, Authorization header, or NAS credentials.
  • A server-supplied profile_id is never trusted; the Rust connection object binds every event to its local Profile and slot.
  • A changed server_instance_id or certificate identity freezes the affected connection instead of silently rebinding it.
  • Companion Profiles never gain local-tool authority from slot assignment alone.
  • The provisional /desktop/v1 contract and Mock Gateway are not evidence of compatibility with an unreviewed real AstrBot Gateway.

First increment

Implement SQLite schema v3 for the two fixed slot assignments, bounded list/assign/clear commands, database and command tests, and a minimal Profile-slot settings surface. This increment intentionally excludes network activation and credential values.