173 行
11 KiB
Markdown
173 行
11 KiB
Markdown
# 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 隐私与人工验收。
|
||
- 当前只具备短时、单前台窗口的手动读取;不得将其宣传为全桌面随机观察或游戏识屏。
|