AstrBot-Desktop/docs/decisions/pending-decisions.md
YokiiroBW 3d1d962461
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(chat): add AstrBot dual-slot chat foundation
2026-07-20 11:31:41 +08:00

8.8 KiB

Pending Decisions

PD-0001: Forgejo transport for the development machine

  • Status: resolved for HTTP push; SSH remains unavailable
  • Current value: ssh://git@localhost:18086/YokiiroBW/AstrBot-Desktop.git
  • Push URL: http://192.168.31.210:18085/YokiiroBW/AstrBot-Desktop.git
  • Observation: the authenticated Forgejo API confirmed YokiiroBW/AstrBot-Desktop existed, was empty, used main, and granted push permission before initialization.
  • SSH observation: localhost:18086 refuses connections. 192.168.31.210:18086 answers but rejects the available SSH key.
  • Push observation: Git Credential Manager was cleared and reauthenticated without placing a secret in the repository or chat. The approved non-forced HTTP push succeeded and remote main now points to 0d12b94.
  • Decision: retain the SSH URL as the fetch URL for future key repair and use the explicitly approved HTTP URL as the push URL for this workflow.
  • Safety impact: no force push or history overwrite occurred; feat/p00-bootstrap was created from the pushed baseline.

PD-0002: P00 branch naming

  • Status: resolved for this predevelopment workflow
  • Decision: use feat/p00-bootstrap as explicitly required by the workflow and current user request.
  • Follow-up: subsequent stages use the branch names in AGENTS.md.

PD-0003: Node.js release line

  • Status: monitor during bootstrap
  • Current environment: Node.js 24.
  • Decision: use the installed version initially; pin package-manager and dependency versions in the repository and record any Tauri/Vite incompatibility found by actual builds.

PD-0004: P00 source layout

  • Status: resolved for P00
  • Observation: the architecture document illustrates an apps/desktop monorepo, while the predevelopment workflow recommends root-level src and src-tauri directories.
  • Decision: keep the single desktop application at the repository root during P00 and use Cargo workspace crates for protocol and Mock Gateway isolation.
  • Reason: there is only one application, and the workflow explicitly recommends the root layout; this avoids an extra package layer without preventing a later move if a second application appears.

PD-0005: Source cleanup in the NAS Spike

  • Status: resolved for P00
  • Conflict: the implementation task mentions cleanup after verification, while the workflow and safety rules require source preservation and prohibit irreversible tests.
  • Decision: P00 always preserves source files and tests cleanup policy only as a non-executed plan field.
  • Follow-up: reversible recycle-bin behavior requires a later explicitly authorized Spike.

PD-0006: Provisional desktop gateway contract

  • Status: resolved for P00
  • Decision: define a provisional desktop-v1alpha1 contract and Mock Gateway without claiming compatibility with an unavailable real AstrBot Gateway.
  • Follow-up: authentication fields, error codes, event retention, ACK timing, and capability names require a later real-gateway contract review.

PD-0007: Repository-local Git author identity

  • Status: resolved
  • Decision: the user explicitly approved YokiiroBW <yokiirobw@gmail.com>.
  • Implementation: the identity is configured only in this repository.
  • Result: two Conventional Commit baseline commits were created on main, pushed normally, and followed by scoped feature-branch commits.
  • Safety impact: no global Git identity was changed.

PD-0008: Profile CRUD stage ownership

  • Status: resolved; option A selected by the project owner on 2026-07-18
  • Conflict: docs/01_Architecture_Design.md lists Profile CRUD in stage 1, while docs/02_Codex_Implementation_Tasks.md lists ConnectionProfile CRUD in Batch 2.
  • Decision: implement basic non-sensitive Profile metadata CRUD in P01.
  • P01 scope: Profile list, create, update, and delete; SQLite schema v2; bounded Tauri IPC; strict frontend Schema; basic management UI.
  • P02 scope: companion/operations slot assignment, active connection state, auto-connect validation, switching protection, and server_instance_id conflict detection.
  • Secret boundary: P01 commands accept no Token, password, API Key, Cookie, Authorization header, or NAS credential fields. SQLite stores only non-sensitive metadata and future opaque credential references.
  • Rationale: AGENTS.md gives the architecture document higher priority, and the selected split keeps runtime connection behavior out of P01.
  • ADR: ADR-0004-profile-lifecycle-and-secret-boundary.md.

PD-0009: Real AstrBot Desktop Gateway contract

  • Status: open; does not block local slot persistence or Mock-based tests
  • Current contract: repository-local /desktop/v1 and protocol 1.0 are provisional development contracts created during P00.
  • Missing authority: no reviewed real AstrBot Gateway implementation or server-side contract is available for endpoint, error-code, capability, event-retention, ACK, and authentication compatibility.
  • Safe interim rule: keep the protocol types and dual Mock Gateway deterministic, but do not claim real AstrBot compatibility or silently adapt to AstrBot internal APIs.
  • Stop boundary: changes that would require modifying AstrBot core or bypassing the stable Gateway boundary require explicit review.

PD-0010: Credential enrollment and token lifecycle

  • Status: open before production connection activation
  • Established boundary: credential values live only in Windows Credential Manager; SQLite stores opaque references; React never receives stored access or refresh tokens.
  • Required decision: define enrollment/update/delete failure atomicity, whether user-entered bootstrap credentials may pass once through bounded Tauri IPC without entering React state, and how access/refresh token rotation updates secure storage.
  • Safe interim rule: P02 slot persistence accepts no credential values and cannot activate a real connection.

PD-0011: Authoritative server identity enrollment

  • Status: open before first real connection activation
  • Candidate source: GET /desktop/v1/server-info returns server_instance_id, matching the architecture and provisional protocol.
  • Required decision: define the first-contact confirmation flow, duplicate-instance warning behavior, and whether a changed identity requires a separate Profile or an explicit rebind operation.
  • Safe interim rule: never overwrite an existing server_instance_id during background connection or reconnection.

PD-0012: TLS certificate fingerprint binding

  • Status: open before enabling pinned HTTPS Profiles
  • Requirement: a certificate identity change freezes local-tool permission and the affected connection; TLS validation must never be disabled.
  • Required decision: select a maintained Rust TLS integration that can inspect the validated peer certificate without installing a permissive verifier, and define first-contact confirmation UX.
  • Safe interim rule: preserve validated HTTPS behavior and do not claim certificate pinning until the peer certificate path is implemented and tested.

PD-0013: Real AstrBot transport mapping (OpenAPI/Dashboard vs /desktop/v1)

  • Date noted: 2026-07-20
  • Status: open; research complete; live container probe pending
  • Source review: docs/reports/astrbot-real-protocol-review.md
  • Finding: Local AstrBot clone 4.26.7 exposes /api/v1 developer OpenAPI (API Key + Dashboard JWT) and legacy /api/* routes. Chat streaming is request-scoped SSE from POST /api/v1/chat (plus optional run stream / WebSocket), not a long-lived Desktop Gateway event bus with ACK.
  • Missing on real server relative to provisional Desktop contract: /desktop/v1/health|server-info|capabilities, access/refresh token pair, event ACK, tool.proposal, and /local-actions/* callbacks.
  • Safe interim rule: keep provisional Desktop protocol as the internal normalized model and Mock Gateway contract; implement a Rust AstrBotAdapter for real servers. Do not claim compatibility and do not rewrite the whole client.
  • Open items requiring live container probe: actual SSE type sequence, JWT expiry handling in practice, server-instance identity substitute, dual-profile isolation against one or two containers, and whether operations tooling remains Desktop-local for MVP.
  • Stop boundary: if live probe proves only browser-cookie auth works, or requires AstrBot core changes for basic text chat, pause and escalate before coding the adapter.
  • Interaction with existing open items: updates assumptions in PD-0009 and PD-0011; credential storage remains governed by PD-0010.

PD-0013 live probe update (2026-07-20)

  • Live target http://192.168.31.210:26285 accepted API Key auth and streamed chat SSE from POST /api/v1/chat.
  • Dual usernames/session ids remained isolated on one server instance.
  • Provisional /desktop/v1 remains non-native; adapter approach confirmed.
  • Chat MVP connectivity is unblocked. Server identity substitute, JWT login path, file/WS paths, and operations proposal source remain open.