AstrBot-Desktop/docs/implementation-plan.md
YokiiroBW 350c6fd3ad
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(companion): add dedicated voice and game surfaces
2026-07-27 13:46:42 +08:00

11 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 (completed)

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.

Completion commit: bcc08cf feat(connection): add persistent dual slot assignment.

Second increment (completed)

Implement auto-connect configuration validation, operations switch protection while a runtime operations task is active, and duplicate server_instance_id warnings without silent Profile merge. Auto-connect remains configuration-only and does not start REST/SSE. Operations task begin/end stay internal to Rust for this increment.

The next increment starts with the formal Rust-owned credential lifecycle. Real Gateway activation remains blocked until PD-0009 through PD-0012 are resolved.

Real AstrBot adapter foundation (added 2026-07-20)

Completed outside the original pure-mock sequencing because live probe unblocked transport decisions:

  1. Internal SSE mapper and TransportKind.
  2. Credential enrollment lifecycle (enroll/clear/load-for-Rust-only).
  3. DualSlotRuntime activate/probe/send skeleton for strbot-openapi and desktop-v1.
  4. Frontend transport + one-shot credential enrollment UI.

Still reserved before claiming end-to-end product chat:

  • Chat UI event rendering
  • Auto-connect runtime start
  • JWT login
  • Identity confirmation UX

Product queue after the real AstrBot foundation

The ordered queue is maintained in docs/implementation-queue.md. The next implementation target is Q1: a shared Rust-owned chat runtime and normalized AstrBot event subscription.

  1. Q1 normalized chat runtime
  2. Q2 chat/session persistence
  3. Q3 main-page chat MVP
  4. Q4 shared-state quick chat window
  5. Q5 status bubble and tray integration
  6. Q6 pet state/resource foundation
  7. Q7 multi-monitor and game-mode strategy
  8. Q8 voice, proactive messages, and game companionship
  9. Q9 release hardening and acceptance build

The quick window and bubble are presentation surfaces over the same runtime; they must not create independent network clients or permission scopes.

2026-07-20 增量计划更新

  1. 启动时读取并校验自动连接 Profile。
  2. 按固定槽位独立激活 Rust-owned Runtime。
  3. 为失败槽位保留可诊断状态,不影响另一槽位。
  4. 补充检查结果并进入聊天运行时事件订阅。

2026-07-27 规划增量:陪伴体验拆分与屏幕感知(未开始)

  1. 先以 docs/reports/companion-ui-and-screen-awareness-plan-2026-07-27.md 作为 C1–C8 的设计基线;本轮不编写产品代码。
  2. 将“聊天、语音聊天、游戏陪玩”定义为共享同一运行时的三个展示入口,不允许为页面复制连接、会话或权限。
  3. 将定时屏幕感知放入“诊断与设置”,并将开关、授权、调度、限频、随机判定和停止路径视为同一 Rust-owned 安全能力。
  4. 在 PD-0014 获得范围决定前,不扩展当前的单窗口授权捕获;在 WGC Spike 通过前,不实现硬件加速游戏陪玩。
  5. 后续每阶段均需更新 docs/progress.md、错题本、相关 ADR/协议文档及验收证据后才可标记完成。

2026-07-27 C1 完成记录:陪伴入口页面壳

  • 已完成:语音聊天与游戏陪玩从文字聊天中拆出独立导航和懒加载页面,保留一个共享聊天运行时。
  • 已完成:游戏页将 WGC 设为明确的不可用状态,不触发屏幕读取、全桌面捕获、调度或新的 Tauri command。
  • 已完成:导航图标设为 aria-hidden,避免图标字符污染可访问名称;App 回归测试覆盖两个新入口与禁用状态。
  • 已验证:typecheck、lint、Vitest 60/60、Vite 生产构建和本轮文件的 Prettier 检查。

2026-07-27:屏幕感知理解框架(评估完成,未开发)

  • 详细框架:docs/reports/screen-awareness-understanding-framework-2026-07-27.md。
  • 方案 B 的实施顺序固定为 S0 WGC Spike -> S1 范围授权与设置 -> S2 Rust 调度/策略 -> S3 多模态契约与视觉验收 -> S4 游戏陪玩接入 -> S5 隐私与人工验收。
  • 当前只具备短时、单前台窗口的手动读取;不得将其宣传为全桌面随机观察或游戏识屏。