From 952b5d1b3e4202b26ce79a1bd5735489dad11d0a Mon Sep 17 00:00:00 2001 From: knqiufan Date: Fri, 4 Sep 2026 17:23:47 +0800 Subject: [PATCH 1/2] docs(rfc): propose desktop control center --- docs/en/rfcs/0000-desktop-control-center.md | 787 ++++++++++++++++++++ docs/zh/rfcs/0000-desktop-control-center.md | 669 +++++++++++++++++ zensical.toml | 2 + 3 files changed, 1458 insertions(+) create mode 100644 docs/en/rfcs/0000-desktop-control-center.md create mode 100644 docs/zh/rfcs/0000-desktop-control-center.md diff --git a/docs/en/rfcs/0000-desktop-control-center.md b/docs/en/rfcs/0000-desktop-control-center.md new file mode 100644 index 000000000..30b5e5952 --- /dev/null +++ b/docs/en/rfcs/0000-desktop-control-center.md @@ -0,0 +1,787 @@ +- Proposal Name: `desktop_control_center` +- Start Date: 2026-09-04 +- RFC PR: Not opened +- Tracking Issue: [oceanbase/powercontext#1428](https://github.com/oceanbase/powercontext/issues/1428) +- Status: Proposed + +# Summary + +Build a PowerContext desktop control center with **Tauri 2, a shared Web management interface, and the existing +independent Python Server**. The application helps users install and diagnose PowerContext, connect to a local or +remote Server, organize Scopes, inspect and manage Memory and reviewed assets, and act on Handoff and Review items. +Rust owns narrowly scoped desktop capabilities; the Server remains authoritative for domain behavior, persistence, +authorization, and durable work. Installation and native service management retain their existing owners. + +The proposed first qualified platform is **Windows 11 x64 with the SQLite backend**. macOS and Linux follow the same +architecture but require their own installation, security, update, and usability acceptance. A personal preview may +ship earlier; completing #1428 additionally requires the authorization and durable Handoff delivery dependencies +described below. Merging this RFC does not close the tracking issue. + +# Motivation + +PowerContext already has a Python SDK, HTTP APIs, Agent integrations, a Server-owned Web UI, and native per-user service +management. A user still needs to understand several different installation, configuration, version, and diagnosis +surfaces to answer simple questions: Is my Server running? Is my Agent using the correct Scope? What needs review? +Where did a Handoff go? Can I update safely without losing data? + +The desktop should make those questions answerable from one application. Its value comes from native installation +and lifecycle visibility, protected credential storage, notifications, and a consistent management interface. It +should preserve PowerContext's existing ability to serve multiple Agents independently of any open application window. + +This proposal serves three users: + +- A new individual user who wants a working local Server and one selected Agent integration without preparing Python + or building source code. +- An existing CLI or Web user who wants convenient management of an existing deployment without an automatic + relocation of data or replacement of configuration. +- A user of a team-operated Server who needs authenticated, authorized access to shared work and exact Handoff items. + +It does not introduce a chat client, IDE, Agent Runtime, autonomous task orchestrator, new Memory engine, or desktop +database replica. It also does not make the desktop a mandatory dependency of the SDK, CLI, Server, or integrations. + +# Guide-level explanation + +## What users install and where it lives + +Users install a native application called **PowerContext Desktop**. It has its own window, application icon, and, +where available, tray entry. The source lives in the PowerContext repository. Desktop releases contain a trusted local +UI and native host. A local setup also installs a separately versioned Python runtime environment through the unified +installer. A remote-only setup needs neither a local Python runtime nor a local PowerContext Server. + +There are two connection choices: + +| Choice | User experience | Ownership | +| --- | --- | --- | +| This computer | Set up or connect to this OS user's local Server; inspect its service and integrations | The existing service layer and OS service manager own the Server | +| Remote Server | Enter an HTTPS endpoint and credential; inspect the connected Server and permitted resources | The remote operator owns runtime installation, data, and service lifecycle | + +Connection profiles remember endpoint settings and a reference to a protected credential. The window shows one active +connection and its current Scope selection. Local service controls are available only for a verified, locally managed +installation. Connecting to a remote Server never turns its configuration into a local service definition. + +## First successful use + +1. The application explains local and remote setup. For local setup it displays the release, components, data + location, selected Agent hosts, and changes the installer proposes to make. +2. The user approves that concrete plan. The installer verifies immutable artifacts, installs the runtime and selected + integrations, registers the per-user service, and reports component results. Failures retain a clear recovery path. +3. The user can start with a minimal configuration without a model. Explicit Memory storage and available full-text + recall provide the first success path. Generation, extraction, vector retrieval, and model-dependent features show + their actual capability requirements. +4. The user chooses or creates a Scope, explicitly stores a small Memory item, and recalls it from the same Scope. + Source import is also available, but accepting a Source does not mean extraction has produced Memory. +5. The selected Agent integration is checked separately. The UI distinguishes installation from successful host + loading and a real capture/recall check; it does not label an untested integration healthy. +6. The user can find pending Review items and, when supported, the Handoff inbox. A notification opens the exact + authorized item after the application refreshes its current state. + +An existing installation is discovered and inspected before any change is proposed. A reachable process with unknown +ownership can be connected to, but the desktop does not kill it, replace its environment, or take ownership of its port. + +## Main screens + +| Screen | Required behavior | Boundary | +| --- | --- | --- | +| Overview | Active connection, Server readiness, local service state, supported features, attention items, recovery actions | Readiness, installation, authentication, and authorization are separate states | +| Projects and workstreams | Present Scopes, organization, and `all` / `subtree` / `exact` observation selections; manage supported bindings | Project/workstream names are presentation labels for Scopes, not a second identity system | +| Memory and assets | List/search/read Memory; explicitly remember, revise, or retire through supported APIs; inspect Experience, Skills, provenance, and lifecycle | Preserve exact references and existing Review/publication rules | +| Review | Filter and inspect Candidate items; approve, reject, or revise with conflict feedback | Server-authorized actions on the displayed Candidate version | +| Handoff | Exact authorized Handoff detail, read-only reports, and the delivery inbox when available | Access discovery, delivery, viewing, acknowledgement, and task outcome remain distinct | +| Sources and connectors | Import selected content, inspect supported Source state, and show available connector health and recovery | Background ingestion belongs to Server/connector workers; absent management APIs are shown as unavailable | +| Agents and integrations | Select maintained distributions; show declared support, installed version, diagnostics, and permitted binding changes | Reuse distribution and installer contracts; do not rewrite host adapters | +| Settings and diagnostics | Connections, credentials, language, notification choices, data locations, versions, updates, and redacted diagnostics | Remote administration requires separately advertised and authorized APIs | + +The first release does not promise a complete connector marketplace, a Handoff editor, execution of arbitrary Skills, +or every operation exposed by the SDK. Supported pages must still complete their stated user journey; unavailable +features cannot appear as working placeholder controls. + +## Closing the window and working offline + +Closing the last window hides the application when the tray is available. Explicit Quit exits the desktop. If the tray +is unavailable, the window explains its close behavior and offers a clear Quit action. Neither action unregisters or +terminates the independently managed Server. Starting the desktop at login and starting the Server at login are +separate settings. + +Notifications require the desktop process to be running in this release. The Server retains durable work and the +Handoff inbox while the desktop is closed; opening the application refreshes authoritative state. An offline remote +connection shows its disconnection and does not queue domain writes. A local Server can still provide capabilities +that do not require an unavailable remote model or service. + +# Reference-level explanation + +## 1. Baseline and dependent work + +The implementation baseline is upstream `master` at +[`f0f288abecaccb97e1fe97d991b87b808bbebfbd`](https://github.com/oceanbase/powercontext/commit/f0f288abecaccb97e1fe97d991b87b808bbebfbd), +checked on 2026-09-04. The following are implementation facts at that baseline, not claims about a released desktop: + +| Existing surface | Reusable capability | Gap relevant to this RFC | +| --- | --- | --- | +| Public HTTP contract | Scopes and bindings, Memory, Source ingestion, Candidates, Skills, exact Handoff operations, statistics and reports | No desktop compatibility handshake or durable Handoff delivery inbox contract | +| Web UI | Jinja templates and JavaScript modules for Overview, Skills, Review, and Handoff Report | Some support routes are under `/dashboard`; desktop business access must use public APIs | +| Native service layer | `service install`, `service status --json`, `service uninstall`; independent per-user service registration | No existing public `service start/stop/restart --json` interface | +| Configuration | Minimal Server configuration validation without inference; model capabilities remain optional | Desktop onboarding and protected configuration editing are not implemented | +| Authentication | Optional deployment-wide static Bearer authentication | Resource-level Principal/role enforcement is not implemented at this baseline | +| Integration manifest and diagnostics | Version-specific capability declarations and structured integration checks | Neither is a live Handoff receiver registry | +| Released package | Published `0.1.0` remains distinct from development `master` | `0.1.0` does not include the native `service` command | + +The installation documentation now distinguishes released and unreleased paths. The desktop must use a release whose +manifest explicitly supports the required runtime/service contracts, or clearly label a pinned prerelease. It must not +silently install moving `master`, combine unrelated integration/runtime revisions, or advertise `0.1.0` service support. + +| Dependency | State at baseline | Required coordination | +| --- | --- | --- | +| [RFC 1299](1299_local_server_availability_and_service_installation.md) | Service architecture and implementation available on `master` | Preserve one service owner and structured status semantics | +| [RFC 1345](1345_scope_organization_and_agent_integration.md) | Scope model and integration contracts available | Reuse Scope identity, organization, bindings, and explicit publication | +| [RFC 1396](1396_handoff_access_control.md), implementation [#1398](https://github.com/oceanbase/powercontext/pull/1398) | RFC merged; implementation PR open | Team/resource-sharing acceptance requires Server-side enforcement and authorized discovery | +| [#1419](https://github.com/oceanbase/powercontext/issues/1419) | Handoff delivery tracking issue open | Owns receiver enrollment, envelopes, durable inbox, delivery states, retry, expiry, and recovery | +| [#1406](https://github.com/oceanbase/powercontext/issues/1406), RFC [#1408](https://github.com/oceanbase/powercontext/pull/1408) | Installation tracking issue and RFC PR open | Owns bootstrap, plans, component installation, version records, and recovery | +| [#1405](https://github.com/oceanbase/powercontext/issues/1405), RFC [#1410](https://github.com/oceanbase/powercontext/pull/1410) | Distribution tracking issue and RFC PR open | Owns canonical Agent distributions, target profiles, and host configuration rules | +| [RFC 1400](1400_source_definition_and_observation_model.md) | Source identity and observation design in the repository | Preserve Source semantics; connector management needs its own supported surface | + +Open proposals supply coordination constraints, not implemented protocols. Their final contracts take precedence over +illustrative names in this RFC. A personal preview may use existing single-deployment functionality; it cannot claim +resource-isolated team sharing or reliable delivery before those dependencies pass acceptance. + +## 2. Component ownership and repository layout + +```text +Trusted Web UI (shared presentation and page behavior) + browser adapter ---------------------> public Python Server HTTP API + desktop adapter -> narrow Rust bridge -> public Python Server HTTP API + | + +-> OS credential store, tray, notifications, file picker + +-> unified installer and existing service interface + +OS service manager -> independent Python Server -> domain persistence and durable workers +Unified installer -> verified runtime/integration artifacts and installation records +``` + +| Component | Owns | Must not own | +| --- | --- | --- | +| Shared Web UI | Navigation, localized presentation, forms, supported user actions | Authorization decisions, domain persistence, background ingestion | +| Rust desktop host | Restricted OS integration, protected credential access, authenticated transport, bounded local preferences | Memory/Handoff semantics, database access, another installer or service supervisor | +| Python Server | Public APIs, Runtime capabilities, domain validation, authorization, persistence, durable processing | Dependence on an open desktop window | +| Installer and distribution layers | Artifact identity, bootstrap, install plan, host configuration, ownership records, upgrade recovery | Desktop-specific business rules | +| Existing service layer and OS manager | Per-user registration, service identity, status, lifecycle | A second desktop-managed daemon competing for the same endpoint | + +Add `desktop/` to the existing repository, containing the Tauri host under `desktop/src-tauri/`, desktop entry assets, +packaging configuration, and desktop acceptance harnesses. The initial implementation extracts reusable presentation +and transport boundaries from the existing Web UI. Server-served templates/static resources remain under +`src/powercontext/server/` and continue to be included in Python wheels. + +Desktop packaging may introduce a frontend build for this independently built application. It must not require Node, +Rust, or desktop dependencies to install the Python package or run the existing Server UI. Do not make a React/Vue +migration a prerequisite: existing HTML, CSS, and JavaScript modules are sufficient until a concrete requirement +justifies replacing them. Any generated desktop entry markup has a single shared source and is built before release; +the installed desktop does not need to run Jinja or contact a Server to render setup and recovery screens. + +Tauri capabilities, plugins, dependencies, and lockfiles are reviewed and pinned. Desktop-only CI paths are separated +from normal Python development while shared UI/API changes retain their existing test gates. + +## 3. Public API reuse and compatibility + +The desktop is a public API client. It must not import Python Runtime objects, open the domain database, scrape rendered +HTML, or depend on private `/dashboard/*` support endpoints. Shared pages use transport adapters: browser requests use +the Web deployment's authentication flow, and desktop requests use the native bridge. Page code does not implement +its own credential storage or route construction. + +The existing API supports most initial management operations: + +| Area | Existing public surface | Desktop implementation requirement | +| --- | --- | --- | +| Health and capabilities | `/health/live`, `/health/ready`, `/v1/capabilities` | Keep process liveness, runtime readiness, and feature availability distinct | +| Scopes | `/v1/scopes/*`, `/v1/scope-bindings/*`, artifact publication APIs | Reuse exact identities and supported selection/binding operations | +| Memory | `/v1/memory/*` | Respect size limits, citations, revision conflicts, and advertised search modes | +| Review | `/v1/artifact-candidates/*` | Pass expected Candidate versions; show conflicts instead of overwriting | +| Skills and Experience | `/v1/skill/*`, `/v1/experience/*` | Preserve managed lifecycle, exact package references, and Review requirements | +| Handoff and work | `/v1/handoff/*`, `/v1/work/*`, `/v1/handoff-reports/get` | Reuse exact continuation, acknowledgement, outcomes, and read-only reports | +| Sources | `/v1/sources/content`, Source definitions, observations, connector checkpoints | Use supported ingestion contracts; checkpoint APIs are not a connector control plane | +| Statistics | `/v1/stats` | Use Server-authorized projections, not client-side aggregation of unrestricted records | + +Missing public projections must be added to `openapi/powercontext.yaml` before their desktop consumers ship, then +generated with `make api-generate` and checked with `make contract-test`. The same public routes and enforcement are +available to other clients. This RFC adds no implementation endpoints by itself. + +This proposal introduces an additive, authenticated **`GET /v1/server-info`** handshake. Its initial contract should +contain `schema_version`, `product`, a persistent opaque `server_id`, `package_version`, `api_contract_version`, and +versioned `feature_contracts`. These fields describe deployment identity and protocol compatibility; runtime provider +availability continues to come from `/v1/capabilities`. The route must exclude filesystem paths, credentials, user +inventories, and unauthorized resource metadata. It follows the Server's authentication policy and exposes only the +minimal connection metadata needed by an authenticated client. + +The exact OpenAPI schema and compatibility identifiers are a Server-owned prerequisite. Each desktop release declares +which contract versions and optional features it understands; package-version string comparisons alone do not decide +compatibility. Unknown optional features are ignored. An incompatible required contract blocks affected operations +with an upgrade explanation. A legacy Server without this handshake remains identifiable as legacy/compatibility +unknown and receives only explicitly tested support; it must not acquire features based on guessed versions. + +`server_id` is a correlation identifier, not proof of ownership or authentication. Credentials, validated TLS, and +verified local installation/service records establish connection trust. An unexpected identity change invalidates +pending actions and cached selections and requires the user to reconnect deliberately. A handshake must not trigger +an automatic runtime upgrade, credential transfer, or migration of the remote deployment. + +## 4. Connection profiles, transport, and the native bridge + +Profiles persist a local opaque profile ID, display name, normalized endpoint including any supported base path, +connection mode, credential reference, TLS trust configuration, and observed compatibility metadata. They contain no +domain records. Remote profiles cannot select a local executable or service environment. + +The first release has one active connection per window and one desktop instance per OS user and release channel. +Additional launches activate the existing instance using OS-user-restricted native IPC. The desktop does not expose +an extra HTTP management listener. Profile changes increment a connection generation, cancel outstanding reads, clear +private views, and discard late responses from the previous generation. A submitted write stays associated with its +original endpoint, Principal, Scope, and exact item; switching profiles cannot retarget it. + +Transport must apply the same loopback policy as the existing client, including the shared cases in +`tests/fixtures/transport_loopback_vectors.json`: + +- Non-loopback endpoints require HTTPS and normal hostname/certificate validation. Loopback HTTP is permitted under + the existing client policy; loopback reachability alone does not authenticate a Server. +- Reject endpoint user information, query strings, and fragments. Credentials are never embedded in URLs. Preserve a + supported API base path without allowing operation paths to escape it. +- Reject redirects for authenticated API requests in the first release. Do not forward credentials to a different + host, scheme, or port. A custom CA, if supported, is explicitly configured for one profile; there is no persistent + "disable certificate verification" setting. +- Apply bounded connect/read deadlines, body sizes, pagination, and cancellation. Errors identify transport failure, + certificate failure, authentication failure, denial, conflict, incompatibility, and service unavailability separately. +- Remote profiles begin with a credential. A successful public health response is insufficient evidence of authenticated + management access. Multi-user use additionally requires the resource-authorization contract in section 7. + +Rust injects the selected credential into requests. The WebView receives data and safe errors, not a credential-read +API. Bridge commands represent allowlisted public operation IDs and typed parameters, profile selection, write-only +credential replacement, bounded file selection/import, diagnostics, and supported installer/service operations. + +There is no arbitrary `fetch(url)`, shell execution, raw filesystem, process-kill, or database bridge. The renderer +cannot choose an executable, command line, release source, destination path, or credential header. Native validation +checks the selected profile, operation, parameters, limits, and current action context independently of UI controls. +File operations use native-selected handles or constrained destinations, not arbitrary renderer-provided paths. + +Only packaged local UI documents receive Tauri capabilities. Remote Server responses are treated as untrusted data; +remote HTML must not be loaded into a privileged window. Use a restrictive CSP without remote scripts or unrestricted +inline execution. Render text and supported Markdown inertly; imported content cannot start commands, fetch remote +images, navigate the privileged window, or invoke IPC through embedded markup. Opening an external HTTP(S) link is an +explicit user action in the system browser. Other URL schemes require a separately reviewed, allowlisted integration. + +## 5. Local service lifecycle and installation control + +The local Server retains RFC 1299's per-user identity: systemd user service on Linux, LaunchAgent on macOS, and Task +Scheduler on Windows. Desktop setup does not request root, SYSTEM, or a second machine-wide service. Service settings +remain loopback-local and come from the validated local installation environment. + +The current structured status fields are preserved as separate facts: + +| Field | Meaning for the desktop | +| --- | --- | +| `support` | Whether this platform/environment supports native registration | +| `registration` | Whether a registration exists and is valid | +| `definition` | Whether executable and environment identity are current | +| `manager_ownership` | Whether the loaded manager entry belongs to PowerContext | +| `manager` | Active/inactive/failed/unknown manager state | +| `server_liveness` | Endpoint live/unreachable/unknown | +| `endpoint`, `log_location`, `recovery_action` | Local inspection and recovery information, shown with appropriate redaction | + +`service status --json` can return a valid unhealthy result with a nonzero exit code. Parse the documented result +before deciding that command execution failed. A live endpoint with foreign or unknown ownership is not a healthy +managed installation. Do not kill an occupied port, delete another registration, or replace an unknown executable. + +Reuse `service install` reconciliation and `service uninstall` semantics through the service owner. If the product +needs explicit start, stop, or restart, those operations and their machine-readable results must first be added to +that owner; current CLI commands do not provide them. Until available, hide unsupported controls and offer supported +recovery. Never implement "Stop" by uninstalling the service. + +The desktop consumes the installation plan, verified component results, and recovery semantics owned by #1406 and its +installation RFC. A versioned, non-interactive machine interface is a prerequisite for desktop-managed installation. +The desktop must not implement another installer engine or infer success from process exit alone. In particular, +#1408's proposed phases and structured output do not yet define public `plan/apply/status` commands or JSON schemas. + +That interface needs to expose a reviewable plan, immutable component identities, affected locations, ownership and +compatibility checks, observable progress, cancellation boundaries, durable operation identity, component outcomes, +and recovery after an interrupted client. Resolve/preflight remain non-mutating. Revalidate a stale plan before +application. The installer owns concurrent-operation locking and its durable journal; multiple entrypoints must not +race the same installation. + +Runtime and host components can succeed independently. An `uncertain` result requires verification before retry; +`installed` is not proof that a host loaded successfully. The desktop displays the producer's `unsupported`, `skipped`, +`installed`, `current`, `stale`, `failed`, or `uncertain` states without inventing a global atomic rollback across hosts. + +Window closure can leave an installation in the background only if its owner supports durable execution and recovery. +Otherwise the application keeps the operation visible and offers cancellation only at safe boundaries. A forced exit +must be recoverable from the installer's records. Do not promise that an ordinary Tauri-spawned child survives Quit. +The steady-state Python Server is always managed independently by the existing OS service registration. + +## 6. Credentials and local configuration + +Store client credentials in an explicit native credential-store adapter: Windows Credential Manager for the initial +Windows target, macOS Keychain and Linux Secret Service when those platforms qualify. Desktop preferences store only +opaque references. An unavailable or locked backend requires unlock, session-only use, or a separately supported +encrypted-vault flow; there is no silent plaintext fallback. Tauri Stronghold can implement a vault, but it is not +itself the OS credential store and is not required for the first target. + +A credential typed or pasted into a trusted setup form may exist transiently in its input and write-only IPC payload. +Clear it after submission, do not expose a read-back operation, and do not store it in WebView local/session storage, +URLs, command arguments, logs, diagnostics, crash reports, or notifications. Native transport redacts authorization +headers and sensitive request/response fields before producing observable errors. Tokens copied by users may also +exist in the OS clipboard; the application does not claim to protect against arbitrary software running as that user. + +Server authentication/provider secrets and desktop client credentials have different lifecycles. The independent +Server must obtain its own configuration without requiring a running desktop or an unlocked desktop vault. Local +setup delegates validated configuration generation, restrictive file permissions, and environment identity handling +to the installer/service configuration owner. Never put credentials in a service command line. Configuration changes +that affect a registered environment require the service owner's reconcile procedure. + +Discovery reads only known installation/service records and explicitly selected configuration files. Do not scan +unrelated home directories, import all ambient environment variables, or copy Server/provider credentials into UI +preferences. Sensitive configuration changes show their scope and required restart/reconcile action before application. +Removing a desktop profile removes its credential reference and offers deletion of that credential; it does not delete +credentials or environment files used by the independent Server or Agent hosts. + +## 7. Authentication and resource authorization + +The existing static Bearer middleware authenticates a deployment-wide trust boundary. It does not establish team roles +or resource-level sharing. A personal preview may connect to such a deployment with an explicit shared-trust mode. +Normal desktop-managed local installation should enable Server authentication, while attaching to an existing +unauthenticated loopback deployment presents its actual access policy without silently changing it. + +Team-connected use requires the Server enforcement described in RFC 1396 and its implementation work. The Server +resolves the trusted Principal; renderer input, an Agent name, `receiver`, or a receiver's self-reported authorization +check cannot establish identity or grant access. A desktop cannot compensate for missing backend authorization by +hiding buttons or filtering a fully retrieved dataset. + +Use the Server's current-Principal discovery and supported access checks to explain available actions. They are +advisory UI prechecks: every body read, exact continuation, acknowledgement, Review action, and mutation still passes +the Server's current authorization enforcement. In particular: + +- Scope organization does not imply access inheritance or Context sharing. +- Candidate reads and Review mutations follow their distinct read/review permissions. +- A grant to one committed Handoff revision does not grant the latest Handoff, adjacent revisions, an entire Scope, + a report, or unrestricted Memory search. Evidence follows the exact citation manifest and its authorization rules. +- Skill publication preserves both resource and publication permissions. A target identifier is an operation + parameter, not a new authorization resource or proof of ownership. +- Collections, totals, and search results are authorized before repository query/pagination. An unavailable safe + filtering path must fail explicitly; the desktop must not fall back to an unrestricted list and local filtering. + +Cache entries, opaque list cursors, selections, and notification metadata are isolated by profile endpoint, current +Principal or credential generation, and query. Switching identity clears prior private state. Authorization-check +results are not durable permission grants. An expired credential stops protected requests and prompts reauthentication; +a denied action retains its distinct explanation. Neither condition triggers automatic credential reuse on another +profile or unbounded background retries. + +## 8. Scope, asset, and Review behavior + +Project and workstream views use existing opaque Scope IDs and organization. A repository path, branch, session ID, +Agent name, or display label is not a Scope identity. Parent organization does not create transitive Context references, +transfer ownership, or publish Artifacts. Cross-scope visibility and publication use their explicit existing APIs. + +Observation selection (`all`, `subtree`, `exact`) is separate from the exact Scope used for a write or integration +binding. Forms display the destination Scope; actions capture it when submitted. Changing the global selector while +a request is in flight cannot redirect the mutation. Binding edits show the affected integration and its supported +selection semantics rather than assuming all hosts implement the same behavior. + +Memory search uses supported Server search modes and limits. A missing embedding/generation capability disables only +the affected operation. The UI preserves Memory citations and exact Artifact references and labels pending Sources, +Candidates, committed Artifacts, and retired entries distinctly. It does not present accepted Source input as already +extracted Memory or a pending Candidate as a published Skill. + +Review reuses Candidate expected-version checks. On a conflict the application reloads the authoritative Candidate +and explains the intervening change; it does not silently approve a newer version. Managed Skill lifecycle changes +preserve their generation checks, and package publication consumes reviewed exact packages. Downloading, inspecting, +or publishing a package does not authorize the desktop to execute its scripts. + +## 9. Handoff discovery, delivery, and actions + +Three views have different purposes: + +| View | Authority | Meaning | +| --- | --- | --- | +| Handoff Report | Existing report API | Read-only projection of selected Scopes and their latest exact Handoff | +| Shared with me | RFC 1396 authorized resource discovery | Exact resource identities the current Principal may access | +| Handoff inbox | #1419 delivery contract | Durable delivery records for the receiver, including their supported state and recovery | + +An access-list page cursor is not an incremental notification cursor. Granting access does not deliver a Handoff or +mark it unread. Candidate Review and remote Skill receiver/reconciliation APIs also cannot stand in for Handoff +delivery. The desktop does not define a second envelope, receiver registry, receipt protocol, or retry scheduler. + +The #1419 owner must supply the delivery contract needed by all consumers: versioned envelopes and exact references, +trusted receiver association, durable listing and recovery, deduplication identity, supported pagination/event +cursor semantics, expiry, cancellation, and terminal/retryable states. The desktop consumes these as opaque identities +and supported operations, scoped to the current endpoint and Principal. Until implemented, the UI may provide reports +and authorized discovery, but must label the durable delivery inbox unavailable. + +Opening an item resolves its original exact `ArtifactReference`, rechecks current authorization, and fetches current +delivery state. It does not substitute `latest`. A missing, expired, canceled, or revoked item explains that outcome +without exposing cached body content. Access to one exact revision must not open a broader Scope report as a fallback. + +Existing exact Continue and Acknowledge operations remain authoritative. Receipt values such as `accepted`, +`needs_clarification`, and `declined` keep their current meanings. An accepted receipt requires the receiver's actual +live-state, capability, and authorization observations; simply viewing a desktop screen cannot attest to another +Agent's environment. The desktop offers acknowledgement only when a supported flow supplies the required checks. +Otherwise it routes the user to the integration that can perform them. + +If a maintained Agent host supports exact-item launching, use its declared integration mechanism and pass only the +bounded exact selection it accepts. Otherwise provide a supported copy/open workflow without credentials or domain +bodies in a URL. The desktop does not invent a host deep link or run an Agent task itself. Local links and notification +activations are navigation requests only: validate their profile/item association and perform no automatic mutation. + +Viewing, marking read where supported, successful delivery, granting access, a receiver's accepted receipt, and a +recorded Task Outcome are different actions. The UI names them separately and never advances one as a side effect of +another unless that transition is explicitly defined by the owning Server contract. + +## 10. Notifications and background behavior + +The Server inbox and Candidate state are authoritative. OS notifications are best-effort hints, not a durable queue +or an exactly-once delivery guarantee. Initially subscribe or poll only the active connection. Use an existing +supported incremental contract when available; otherwise bounded, backed-off polling is acceptable for Review state. +Polling a Candidate list provides current pending work, not a complete history of every intermediate transition. + +Requirements for notification consumption are: + +- Derive notification identity from the producer's stable item/event identity and exact revision where applicable. + Persist only bounded deduplication metadata and opaque cursors; never persist Memory, Source, Handoff, Prompt, or + Prepared Context bodies in the desktop notification store. +- Apply producer-defined resume, cursor-expiry, and gap-recovery semantics. If only current-state listing is available, + refresh that state and present a summary; do not invent missed delivery events or reinterpret a pagination cursor. +- Isolate metadata by endpoint and Principal. Clear it on credential/identity changes; bound its retention and size. + Treat a locally displayed notification as separate from a Server-side read or acknowledgement operation. +- Poll with jitter, backoff, request limits, and cancellation. Coalesce bursts and suppress repeated offline/auth errors. + Stop protected background requests on credential expiry; offer one useful recovery indication. +- Use a generic message such as "PowerContext has items needing attention" by default. Notifications carry only + approved bounded metadata and a local opaque navigation handle. Do not include content, credentials, private paths, + sensitive titles, or unreviewed Server error text, including on the lock screen. +- On click, activate the application, restore the appropriate profile deliberately, and reauthorize the exact item. + Stale or spoofed activation handles do not switch credentials silently or execute actions. + +Request OS notification permission with an explanation at first use. Permission denial leaves in-app counts and +inbox access functional. A fully exited desktop receives no notifications in this release; the next start restores +current Server state. If tray support is unavailable, keep ordinary window navigation and Quit usable. Test real +installed notifications and cold activation, not just an in-process mock. + +## 11. Sources, connectors, and integrations + +First support explicit text entry and bounded UTF-8 text-file import through the native file picker. Show destination +connection, Scope, intended Source identity, and size before transmission. A selected file is read through a bounded +native handle; prevent path substitution, directory traversal, and following a changed link into a different file. +The Server's content limits and validation still apply. Do not silently scan a directory or the user's home. + +For a remote connection, transfer approved bytes using the public content-ingestion contract. A local path is not +something a remote Server can open. Preserve Source identity, content digest, and provenance without unnecessarily +disclosing the full local path. Repeated imports obey the Source contract's identity/conflict rules; changing content +under an immutable identity is not treated as a successful duplicate. + +RFC 1400's Source definitions, observations, and checkpoints do not define connector discovery, scheduling, provider +credentials, or plugin execution. First-release connector views are limited to supported Server metadata and actions. +Additional management APIs belong to the connector/Server owner and require public contracts before those controls +ship. Desktop closure cannot stop an accepted connector job; worker credentials and checkpoints cannot live only in +the desktop. A partial crawl must not be interpreted as deletion of unseen content. + +For Agents, consume the maintained distribution model in #1405/#1410 and release-specific capability declarations. +The existing `integrations/capabilities.toml` is a repository version contract, not a live public HTTP capability API +or receiver directory. The UI separately displays: + +1. What the selected distribution declares it supports on this host/platform/version. +2. What the installer records as installed and who owns it. +3. What structured diagnostics verify about loading, connectivity, Scope selection, capture, and recall. +4. Runtime or receiver enrollment state, only when its owner exposes that fact. + +Use actual structured diagnostic interfaces, including `doctor integrations --json`, rather than parsing human text or +counting installed files/tools. Unsupported or unobserved checks remain explicit. Installation is opt-in per selected +host. Configuration merging, canonical package identity, hook behavior, and distribution repair belong to their +existing owners; the Rust host must not copy these rules or automatically rewrite every detected Agent configuration. + +## 12. Offline operation, retry, and concurrent changes + +The first release maintains no persistent local domain cache or offline write queue. An offline remote view hides +private content and displays connection state; optional unsent form input remains volatile and visibly unsaved. +Reconnection refreshes compatibility, identity, authorization, and selected resource state before enabling mutations. +An available local Server continues to support its own offline capabilities; the desktop does not promise offline +generation when its configured model requires the network. + +Read retries are bounded and cancellable. Mutation retry follows the operation's public contract. If the Server +supports an idempotency key, reuse the same key for the same logical operation. A timeout after submission is an +unknown outcome, not proof of failure: verify authoritative state or offer inspection before retry. Do not replay a +Review approval, Handoff receipt, import, publication, or installation blindly. Actions with no safe verification or +idempotent retry path show that uncertainty and require a fresh, explicit decision. + +Concurrent CLI, Agent, Web, or desktop mutations remain valid. Respect existing revision/version checks, show the +refreshed item on conflicts, and preserve user intent without silently applying it to a new revision. Pending UI +actions carry their original connection/identity generation and exact destination. Late results never populate a +different profile's screen. + +## 13. Distribution, updates, and recovery + +The initial Windows distribution uses a signed per-user installer. A local bootstrap must work without preinstalled +Python, Rust, Node, Git, or a compiler. The installer owner supplies a verified interpreter/runtime environment and +maintained integration artifacts for the selected OS and architecture. A remote-only installation omits that runtime. +Online and any offered offline packages declare their included components and remaining network requirements. + +The current service implementation resolves a Python executable and requires an adjacent `pythonw.exe` on Windows. +Therefore a frozen Python executable is not a drop-in runtime replacement. Prefer the installer-owned versioned Python +environment. Any future frozen-runtime design needs explicit service compatibility work and platform qualification. +Tauri sidecar packaging may distribute a helper, but it does not transfer Server lifetime to Tauri's child processes. + +The release plan distinguishes desktop UI/host version, Python runtime version, API contract version, integration +distribution versions, and persistent data compatibility. Resolve a human-friendly channel to an immutable manifest; +record exact artifact locators, digests, OS/architecture, and compatibility. Release trust requires a signed artifact +or manifest bound to a trusted publisher; a checksum downloaded from the same untrusted location alone is insufficient. +Keys and permitted update sources are pinned outside an arbitrary renderer or remote Server response. + +Tauri's signed updater can update the desktop component. It does not coordinate Python environments, Agent +configurations, service registration, or database migrations. The unified installer owns that multi-component plan. +The desktop must never silently upgrade a remote Server or independently overwrite an installation shared with Agents. + +An update follows these rules: + +1. Resolve and display compatible immutable versions, affected components, downtime, data compatibility, and recovery. + Check free space, ownership, credentials needed for verification, and concurrent installer activity. +2. Verify artifacts before staging them beside the existing version. Retain the last verified installation record. + A download or signature failure leaves the running installation usable. +3. For a runtime switch, use the service owner's supported quiesce/switch/reconcile path. Its contract must specify + handling of in-flight and durable work; the desktop does not kill a process after a guessed timeout. +4. Run readiness, compatibility, and selected integration verification before recording the new installation as + healthy. Report component results individually when only part of the plan succeeds. +5. Roll back executable/configuration changes only where the installer declares rollback safe. Data migrations belong + to the Server/runtime owner. An older runtime must not reopen an incompatible upgraded store. Before an irreversible + migration, the plan needs a supported backup/restore or explicit forward-recovery path and user confirmation. +6. On interruption, reopen the durable operation record, verify uncertain components, and resume or repair through the + owner. Never infer that an interrupted operation rolled back successfully. + +Do not copy live database files as an improvised backup. Backup, quiescence, and restore must be consistent with the +actual persistence backend. Schema migrations and backup APIs absent from the owner block the corresponding automatic +upgrade path; they are not implemented inside Rust. + +Stable is the default channel; prereleases require opt-in and clear labels. Channel changes do not bypass data or API +compatibility checks. The initial release offers update notification and explicit application, without unattended +runtime upgrades during active work. + +## 14. Data locations and uninstall + +| Data or artifact | Owner | Default removal behavior | +| --- | --- | --- | +| Desktop executable and packaged UI | Desktop package manager/updater | Removed with the application | +| Connection profiles, UI preferences, bounded notification metadata | Desktop, in a separate per-user application directory | May be removed with an explicit reset choice | +| Desktop credential entries | OS credential store | Remove only entries owned by the selected profile/application | +| Python environments, integration artifacts, installation records | Unified installer | Preserve while still referenced; remove through its ownership-aware plan | +| Service registration and protected Server environment | Existing service/configuration owner | Preserve unless service removal is explicitly requested | +| Memory, Sources, Artifacts, scheduler state, backend data | Server persistence owner | Preserve on application or service uninstall by default | +| Agent host configuration | Distribution/installer owner and the user | Revert only the owned, recorded changes; preserve unrelated edits | + +The Server's `POWERCONTEXT_HOME` or existing platform data-directory rules remain authoritative. Versioned application +directories must not become domain data directories. A local diagnostics page may show resolved data/log locations; +remote connections cannot browse the Server's filesystem. Rust may open a known local location for the user but must +not read or modify domain database contents. + +Offer separate, clearly named actions for removing the desktop, removing the local service, and deleting PowerContext +data. Data deletion is excluded from the first release's automatic uninstaller; a future UI for it requires an explicit +owner-supported workflow and confirmation of the exact local installation and data path. Uninstalling the desktop +must leave an independently installed Server and its Agents usable unless the user separately requests their removal. +Unknown ownership or user-modified files result in preservation and an explanation, not recursive deletion. + +## 15. Diagnostics, privacy, and security scope + +Diagnostics combine desktop version/platform, verified installation/component states, service facts, connection +failure category, supported contract versions, safe request IDs, and bounded timing/error codes. The default export +contains no Memory, Source, Handoff, Prompt, Prepared Context, model output, credential, authorization header, raw +environment dump, connection query, or private absolute path. Do not blindly include arbitrary Server error bodies +or full CLI stdout/stderr; normalize them through a redacted diagnostic model. + +Export is local, explicit, and previewable. Users choose where to save the sanitized file. No automatic upload or +product telemetry is required. Crash reporting is disabled by default; an eventual opt-in mechanism must not transmit +memory dumps or raw request bodies under a claim of content-free diagnostics. Logs have bounded retention and size. + +The threat model includes malicious Server content, imported files, forged notification/deep-link activation, a local +website attempting bridge access, wrong-endpoint credentials, and tampered release artifacts. Its defenses are +trusted local UI, limited IPC, per-profile transport, Server-side authorization, native secret storage, safe rendering, +and authenticated distribution. It does not promise protection from a compromised OS, arbitrary same-user malware, +or an administrator with access to the user's processes and data. + +Security qualification must inspect actual packaged capabilities/CSP, dependency permissions, credential fallback +behavior, and artifact/update verification. Selecting Rust alone is not evidence that those boundaries are correct. + +## 16. Platform, accessibility, and localization + +| Platform | Proposed delivery status | Qualification concerns | +| --- | --- | --- | +| Windows 11 x64 | First qualified target, SQLite local runtime | Per-user signed installation, WebView2 availability/bootstrap, Credential Manager, Task Scheduler ownership, installed notifications, non-ASCII paths | +| macOS | Follow-up qualification | Architecture-specific runtime, Keychain, LaunchAgent, signing/notarization, WKWebView behavior, notification permission | +| Linux | Follow-up qualification with an explicit distro/desktop matrix | WebKitGTK/system libraries, Secret Service availability, systemd user session, tray differences, packaging and notification activation | + +Windows support does not imply Windows ARM support, seekdb availability on Windows, or identical behavior across +all OS versions. A Tauri build succeeding on three targets is insufficient evidence of product support. Each advertised +OS/architecture must pass installed-package acceptance on its declared supported environment. + +Maintain English and Chinese UI/documentation together. Provide keyboard navigation, visible focus, accessible names, +screen-reader semantics, IME-safe forms, high-contrast support, and readable status independent of color. Management +flows must remain usable at an 800 × 600 window and 200% zoom through scrolling or responsive layout, without hiding +confirmation or recovery actions. Preserve user's selected locale and OS theme preferences. + +Before declaring the first target supported, measure cold launch, idle CPU/wakeups, total desktop-plus-runtime memory, +installer/download size, and list/search responsiveness on a documented reference machine. Freeze release budgets +after the architecture spike and before feature expansion. Include WebView2/runtime dependencies and the Python Server +in comparisons; do not advertise a small Rust executable as the total product footprint. + +## 17. Delivery sequence and ownership gates + +Use focused implementation PRs associated with this RFC and #1428. Reuse existing dependency tracking issues; do not +create a duplicate desktop tracking issue or merge the entire product as one change. + +| Phase | Concrete deliverable | Exit gate | +| --- | --- | --- | +| P0: architecture spike and contracts | Trusted bundled shared page in Tauri; public API transport; credential adapter; installed Windows notification; connection/compatibility design; measured prototype | Confirm Windows feasibility and budgets, producer-owned installer/service interfaces, public API gaps, security boundary, and release owner | +| P1: personal preview | New and existing local setup, remote shared-trust connection, service status/recovery, model-optional first Memory flow, selected Agent diagnostics, explicit uninstall behavior | Real pinned artifacts and current supported service contracts; no claim of multi-user resource sharing or reliable Handoff delivery | +| P2: management parity | Scope/binding views, Memory/assets, Review, read-only reports, explicit Source import, supported connector state, bilingual accessibility, protected diagnostics | Public API authorization behavior and revision/conflict semantics preserved; dependency-limited controls accurately represented | +| P3: authorized collaboration | Current-Principal resource discovery, exact-item permissions, #1419 durable inbox/recovery, supported Handoff actions, bounded notifications | RFC 1396 implementation and #1419 contracts pass Server and desktop acceptance | +| P4: qualified first release | Signed installation/update artifacts, recovery, complete first-use journey, independent service lifetime, data-preserving uninstall | All applicable acceptance criteria below pass on Windows 11 x64; published compatibility/support matrix and operational ownership | +| P5: additional platforms | macOS and Linux packages using the same boundaries | Repeat installed-package acceptance for each advertised OS/architecture | + +P0/P1 can proceed without waiting for every collaboration feature, but desktop-managed installation cannot be faked +with a bespoke bootstrap. If #1406's machine interface or Windows bootstrap is unavailable, the preview must be +explicitly connect-only and cannot claim the install acceptance criteria. A preview alone does not complete #1428. + +For #1428 completion, the maintainers should require at least one qualified OS, the issue's complete local setup and +management journey, authorized remote access, reliable Server-backed Handoff inbox consumption, Review/Handoff +notifications, and the documented recovery and uninstall guarantees. Authorization and delivery producers retain their +own tests and release ownership; desktop acceptance validates the end-to-end composition. + +## 18. Acceptance and validation + +These are observable acceptance requirements, not demands to freeze internal function calls, module layouts, or UI +element IDs. Use public API contract tests and installed desktop workflows. Platform-specific tests are required only +for platforms claimed as supported; Server behavior should reuse existing tests where they already protect the contract. + +| ID | Scenario | Required observable result | +| --- | --- | --- | +| AC-01 | Clean first install without Python/Node/Rust/Git; minimal configuration without a model | Verified local runtime/service and selected maintained integration install; explicit Memory store and full-text recall succeed; unsupported model actions explain requirements | +| AC-02 | Existing manual service, stale managed definition, occupied port, or foreign registration | Correctly distinguish states, preserve unknown ownership/data, and offer only supported repair | +| AC-03 | Close window, Quit, restart desktop, and restart the OS session | Independent service and accepted durable work survive desktop exit; login behavior matches service/desktop settings | +| AC-04 | Interrupt download/install/update or fail a signature/readiness check | Old usable state is preserved where possible; component results and uncertainty are explicit; supported resume/rollback respects data compatibility | +| AC-05 | Legacy runtime, incompatible API, mixed integration versions, or changed Server identity | Capability/compatibility limitation is explained; no guessed support, silent retargeting, or automatic remote upgrade | +| AC-06 | Loopback, non-loopback HTTP, invalid TLS, redirect, credential expiry, and authorization denial | Existing transport policy is preserved; no cross-endpoint credential forwarding; failure categories remain distinct | +| AC-07 | Switch profile/Principal while requests or notifications are pending | No previous identity's data, cursor, response, credential, or mutation target appears in the new connection | +| AC-08 | Principal can read only one exact Handoff revision | No latest/adjacent revision, unauthorized evidence, broader report, or Scope content leaks; action requests are reauthorized | +| AC-09 | Restricted lists and Review/publication permissions | Server filters before pagination/totals; unsafe filtering fails; hidden buttons cannot bypass enforcement; permission-specific actions behave correctly | +| AC-10 | Concurrent Candidate/asset update or ambiguous mutation timeout | Version conflict or unknown outcome is shown; no silent approval of a new revision and no blind duplicate mutation | +| AC-11 | Handoff arrives during disconnect, cursor expires, permission is revoked, or delivery is canceled | Producer-defined recovery restores authorized inbox state; original exact reference is retained; navigation cannot acknowledge automatically | +| AC-12 | Installed notification, denied permission, burst of items, full desktop exit, or stale activation handle | Bounded content-free hints, deduplication/coalescing, safe exact navigation, functional in-app fallback, and accurate background limitations | +| AC-13 | File import, repeated Source identity, changed bytes, partial connector crawl, or close during ingestion | Approved content reaches the selected Scope through public APIs; identity/conflicts are preserved; no silent broad import, deletion, or desktop-owned worker | +| AC-14 | Malicious HTML/Markdown, arbitrary IPC parameters, forged link, or wrong profile endpoint | No arbitrary execution/filesystem access, secret read-back, privileged remote navigation, or unintended mutation | +| AC-15 | Secret canaries in tokens, paths, provider configuration, errors, and domain bodies | No canaries in notifications, normal logs, diagnostic exports, URLs, persistent renderer storage, or release telemetry | +| AC-16 | Remove desktop, remove service, or encounter user-modified integration files | Data retained by default; independent components remain usable unless separately removed; unknown/unowned files preserved | +| AC-17 | English/Chinese, keyboard-only operation, IME, screen reader, high contrast, small window, 200% zoom | Setup, connection, review, notification navigation, recovery, and uninstall choices remain understandable and operable | +| AC-18 | Installed release on the reference machine and advertised OS/architecture | Signed artifacts and update path work; measured complete footprint and responsiveness satisfy agreed release budgets | + +Before implementation PRs that change public contracts, run `make api-generate` and `make contract-test`; preserve +normal `make check`, relevant behavior tests, and strict documentation checks. Shared UI changes require Web and +desktop behavior coverage. Desktop packaging changes require an installed-package smoke test; service changes reuse +the service layer's native platform tests. Mocked transport tests alone cannot qualify installation or notifications. + +# Drawbacks + +This adds a maintained native application, a Rust toolchain, desktop JavaScript packaging, signed release operations, +and OS-specific testing to a Python project. Sharing UI code reduces duplicated domain presentation, but extracting +transport and build boundaries still costs work and can affect the existing Web UI. + +Tauri uses different system WebViews across platforms. Rendering, accessibility, authentication integration, and native +notifications need platform validation. Python and optional storage/model dependencies can dominate package size and +resource use, reducing the practical footprint advantage of a smaller desktop host. + +Independent runtime installation is operationally more complex than one executable. It is justified by the Server's +existing role serving Agents while the desktop is closed, but requires coordinated compatibility and recovery. The +complete collaboration product also depends on authorization and delivery work outside this RFC's implementation. + +# Rationale and alternatives + +## Tauri 2 versus Electron + +| Consideration | Tauri 2 | Electron | Decision for PowerContext | +| --- | --- | --- | --- | +| Web UI reuse | HTML/CSS/JavaScript in the OS WebView | HTML/CSS/JavaScript in bundled Chromium | Both can reuse management UI; neither requires rewriting domain code | +| Native host | Rust host with explicitly granted capabilities/plugins | Node.js main process with restricted preload/IPC | A small Rust host fits the limited native duties and contributor preference | +| Distribution footprint | Reuses system WebView, with platform bootstrap dependencies | Ships Chromium and Node.js | Prefer Tauri, but measure the full Python/WebView/runtime distribution | +| Cross-platform rendering | WebView2, WKWebView, and WebKitGTK differences | More consistent bundled Chromium | Electron is advantageous if WebView differences defeat required accessibility or UI behavior | +| Python integration | External runtime or helper | External runtime or helper | Neither solves Python installation, service ownership, or domain schema migration | +| Secrets and updates | Requires explicit credential-store integration and component update design | Native encryption/update facilities still require policy and integration | Neither replaces OS-store qualification, authorization, or installer contracts | +| Team cost | Rust and native plugin expertise; platform qualification | JavaScript/TypeScript ecosystem and Electron expertise | Validate Rust maintenance and release ownership in P0 | + +Choose **Tauri 2** because the product is a native control center around an existing Python Server and a relatively small +Web management surface. Its native host can stay narrow, and there is no requirement for Node.js plugins, a bundled +browser engine, or desktop-side AI execution. Rust is used for OS integration and constrained transport, not as a +performance justification for rewriting Python business logic. + +Electron is the fallback if P0 finds a concrete blocker in the supported WebView's accessibility/rendering, required +native integrations, or sustainable Rust/platform maintenance. Such a switch should retain the same public API, +installer, service, and authorization boundaries. Do not run two production shells in parallel or assert a performance +winner without comparing installed end-to-end prototypes. + +## Other alternatives + +- **Web UI only:** remains supported and is the least expensive choice for remote management. It does not complete + native installation/service diagnostics, OS credential handling, file integration, and installed notification flows. +- **Load a Server page directly in a privileged shell:** reduces initial UI extraction but couples setup to Server + availability and places remote markup beside native privileges. Use packaged local UI instead. +- **Bundle Python as an application child process:** can help a prototype, but closing/updating the desktop must not + interrupt Agents or durable work. Keep the existing independent service owner. +- **Rewrite Runtime/storage in Rust:** duplicates mature domain contracts and migration responsibilities without a + desktop requirement that needs it. It is outside this proposal. +- **A fully native Rust widget UI:** loses existing Web presentation reuse and creates a second management interface. + Reconsider only if a demonstrated requirement cannot be met by the shared Web interface. + +# Prior art + +The project-specific foundations are RFCs +[1299](1299_local_server_availability_and_service_installation.md), +[1345](1345_scope_organization_and_agent_integration.md), +[1396](1396_handoff_access_control.md), +[1400](1400_source_definition_and_observation_model.md), +[1351](1351_standard_skill_package_lifecycle.md), and the +[Server Web UI development guide](../development/server-web-ui.md). The dependency table above distinguishes +implemented surfaces from open installation, distribution, authorization, and delivery work. + +The following official references inform framework and packaging choices; their facilities are not substitutes for +PowerContext's component contracts: + +- [Tauri architecture](https://v2.tauri.app/concept/architecture/) and + [WebView versions](https://v2.tauri.app/reference/webview-versions/) describe the host/UI model and platform engines. +- [Tauri capabilities](https://v2.tauri.app/security/capabilities/) and + [CSP](https://v2.tauri.app/security/csp/) inform the restricted native bridge and trusted packaged UI. +- [Tauri sidecars](https://v2.tauri.app/develop/sidecar/), + [updater](https://v2.tauri.app/plugin/updater/), and + [notifications](https://v2.tauri.app/plugin/notification/) provide component mechanisms that need lifecycle and + installed-package validation. +- [Tauri Windows distribution](https://v2.tauri.app/distribute/windows-installer/), + [macOS signing](https://v2.tauri.app/distribute/sign/macos/), and + [AppImage distribution](https://v2.tauri.app/distribute/appimage/) identify distinct OS delivery requirements. +- [Tauri Stronghold](https://v2.tauri.app/plugin/stronghold/) documents a vault facility; an OS credential-store adapter + is an explicit separate choice in this proposal. +- [Electron documentation](https://www.electronjs.org/docs/latest/), + [security guidance](https://www.electronjs.org/docs/latest/tutorial/security), + [safeStorage](https://www.electronjs.org/docs/latest/api/safe-storage), and + [autoUpdater](https://www.electronjs.org/docs/latest/api/auto-updater) support the alternative assessment. + +# Unresolved questions + +Resolve these cross-owner decisions during RFC review or the named gate, without delegating core business semantics +to the desktop: + +1. **Before RFC acceptance:** confirm the first Windows 11 x64 target, Tauri maintenance/release owner, and the phased + distinction between a personal preview and completion of #1428. +2. **Before desktop-managed installation:** agree the installer/service machine interfaces and Windows bootstrap + schedule. #1406 asks for first-class shell and PowerShell bootstrap; the open #1408 proposal still leaves its engine + and PowerShell timing unresolved. This RFC does not choose the engine's language or invent CLI flags for it. +3. **Before compatibility-dependent management:** settle the proposed `server-info` schema, contract-version policy, + stable Server identity lifecycle, and support window with the Server owner. +4. **Before collaboration release:** agree the delivery/inbox contract and integration launch/receiver checks with + #1419, and qualify authorization with RFC 1396's implementation. Do not treat access-list pagination as event replay. +5. **At P0 exit:** publish measured performance budgets, code-signing/update-key ownership, release CI environments, + and the dependency/security maintenance policy. These are release prerequisites, not claims of present coverage. + +A connector management control plane, additional authentication methods, advanced offline synchronization, and broad +Agent execution are separate designs. Their absence must not be hidden by implementing private desktop protocols. + +# Future possibilities + +After the first complete platform qualifies, add macOS/Linux packages, additional architectures, and background +notifications for explicitly enabled multiple profiles. Further work may add more Source import formats, supported +connector configuration, or system-browser authentication once their Server contracts exist. + +An offline write queue, local domain cache, broader Agent actions, or cloud synchronization would introduce new +consistency and security obligations and require a separate proposal. None is necessary to adopt this RFC. diff --git a/docs/zh/rfcs/0000-desktop-control-center.md b/docs/zh/rfcs/0000-desktop-control-center.md new file mode 100644 index 000000000..317fa4e8e --- /dev/null +++ b/docs/zh/rfcs/0000-desktop-control-center.md @@ -0,0 +1,669 @@ +- 提案名称：`desktop_control_center` +- 开始日期：2026-09-04 +- RFC PR：尚未创建 +- Tracking Issue：[oceanbase/powercontext#1428](https://github.com/oceanbase/powercontext/issues/1428) +- 状态：提案 + +# 概要 + +采用 **Tauri 2、共享 Web 管理界面、独立运行的现有 Python Server**，构建 PowerContext 桌面控制中心。 +用户可以在一个应用里安装和诊断 PowerContext，连接本地或远程 Server，组织 Scope，查看和管理 Memory 及经过 +Review 的资产，处理 Handoff 和 Review 待办。Rust 只负责范围明确的桌面系统能力；业务行为、持久化、授权和持久任务 +仍由 Server 负责。安装和原生服务管理继续使用各自已有的负责层。 + +建议首个完成正式验收的平台为 **Windows 11 x64，本地使用 SQLite 后端**。macOS 和 Linux 沿用同一架构，但需要分别 +完成安装、安全、升级和可用性验收。个人预览版可以提前交付；完成 #1428 还需要本文规定的授权和持久 Handoff 投递依赖。 +合并这份 RFC 不代表关闭该 Tracking Issue。 + +# 动机 + +PowerContext 已有 Python SDK、HTTP API、Agent 集成、Server 托管的 Web UI 和原生用户级服务管理。用户要回答一些 +基本问题，仍然需要理解多套安装、配置、版本和诊断入口：Server 是否运行？Agent 是否使用了正确的 Scope？哪些内容 +需要 Review？Handoff 发到了哪里？升级会不会丢数据？ + +桌面端应让用户在一个应用中回答这些问题。它的价值在于原生安装与服务状态管理、安全保存凭据、系统通知和一致的管理 +界面，同时保留 PowerContext 在没有打开任何应用窗口时，仍能独立服务多个 Agent 的能力。 + +本提案面向三类用户： + +- 新个人用户：不准备 Python 环境、不编译源码，就能用上本地 Server 和自己选择的 Agent 集成。 +- 已有 CLI 或 Web 用户：方便地管理现有部署，不被自动迁移数据或替换配置。 +- 团队 Server 用户：通过认证和授权，访问共享工作以及精确版本的 Handoff。 + +本提案不增加聊天客户端、IDE、Agent Runtime、自主任务编排器、新的 Memory 引擎或桌面数据库副本，也不让桌面端 +成为 SDK、CLI、Server 或集成的必需依赖。 + +# 面向使用者的说明 + +## 用户安装什么，运行在哪里 + +用户安装一个名为 **PowerContext Desktop** 的原生应用，它有独立窗口、应用图标，以及平台支持时的托盘入口。源码 +放在 PowerContext 同一个仓库内。桌面发行物包含可信的本地 UI 和原生宿主；本地模式还通过统一安装器安装独立版本化 +的 Python 运行环境。仅连接远程 Server 时，不需要安装本地 Python 环境或本地 PowerContext Server。 + +应用提供两种连接选择： + +| 选择 | 用户体验 | 由谁管理 | +| --- | --- | --- | +| 这台电脑 | 安装或连接当前系统用户的本地 Server，查看服务和集成状态 | 已有服务层和操作系统服务管理器管理 Server | +| 远程 Server | 输入 HTTPS 地址和凭据，查看所连接的 Server 及自己有权访问的资源 | 远程运维方管理运行环境、数据和服务生命周期 | + +连接配置保存地址设置和受保护凭据的引用。窗口明确显示当前连接及其 Scope 选择。只有经过核验、由本机管理的安装才 +提供本地服务控制。远程连接的配置不会被转换成本机服务定义。 + +## 第一次成功使用 + +1. 应用解释本地和远程模式。本地安装时，先展示发行版本、组件、数据位置、所选 Agent 宿主，以及安装器计划修改的内容。 +2. 用户确认这个具体计划。安装器校验不可变发行物，安装运行环境和所选集成，注册用户级服务，并报告各组件结果。 + 失败时保留明确的恢复入口。 +3. 用户可以不填写模型，先用最小配置启动。显式保存 Memory 和可用的全文检索构成首次成功路径。生成、提取、向量检索 + 等依赖模型的功能，按实际能力显示要求。 +4. 用户选择或创建 Scope，显式保存一条小型 Memory，并在相同 Scope 中召回它。也可以导入 Source，但接收 Source + 不等于已提取出 Memory。 +5. 单独检查所选 Agent 集成。界面区分“已安装”“宿主已成功加载”“实际 capture/recall 检查通过”，不把未检查的集成 + 标成健康。 +6. 用户可以找到待 Review 内容，以及支持时的 Handoff 收件箱。点击通知后，应用先刷新状态，再打开对应的精确授权项。 + +对于已有安装，先发现和检查，再提出修改计划。可访问但归属未知的进程可以作为连接目标；桌面不能擅自终止它、替换其 +运行环境或接管其端口。 + +## 主要界面 + +| 界面 | 必需行为 | 边界 | +| --- | --- | --- | +| 总览 | 当前连接、Server 就绪状态、本地服务状态、支持的功能、待处理事项、恢复操作 | 就绪、安装、认证、授权是不同状态 | +| 项目与工作流 | 展示 Scope 及组织关系，提供 `all` / `subtree` / `exact` 观察视图，管理支持的绑定 | 项目和工作流是 Scope 的展示名称，不增加第二套身份体系 | +| Memory 与资产 | 列表、搜索、读取 Memory；通过已有 API 显式记忆、修订、退役；查看 Experience、Skill、来源与生命周期 | 保留精确引用，以及既有 Review 和发布规则 | +| Review | 筛选和查看 Candidate，批准、拒绝、修订，并显示冲突 | 针对当前展示的 Candidate 版本，由 Server 授权执行 | +| Handoff | 精确授权的 Handoff 详情、只读报告，以及能力就绪后的投递收件箱 | 授权发现、投递、查看、确认接收和任务结果保持区分 | +| Sources 与连接器 | 导入所选内容，查看支持的 Source 状态，以及可用的连接器健康和恢复信息 | 后台摄取由 Server/连接器 worker 承担；缺少管理 API 时明确显示不可用 | +| Agent 与集成 | 选择维护中的发行物，查看声明能力、安装版本、诊断结果，以及授权允许的绑定修改 | 复用分发和安装契约，不重写宿主适配器 | +| 设置与诊断 | 连接、凭据、语言、通知、数据位置、版本、升级和脱敏诊断 | 远程管理操作需要独立声明并授权的 API | + +首版不承诺完整的连接器市场、Handoff 编辑器、任意 Skill 执行能力，或覆盖 SDK 的每一个操作。但已支持的页面必须 +完成所声明的用户流程，不能把不可用功能伪装成能工作的占位按钮。 + +## 关闭窗口和离线使用 + +有托盘时，关闭最后一个窗口默认隐藏应用；明确选择“退出”才结束桌面进程。没有托盘时，窗口应说明关闭行为，并提供 +清晰的退出入口。两种操作都不注销或终止独立管理的 Server。桌面开机启动和 Server 随用户登录启动是两个独立设置。 + +首版系统通知要求桌面进程仍在运行。桌面关闭期间，Server 保留持久任务和 Handoff 收件箱；重新打开应用时刷新权威 +状态。远程连接离线时明确显示断连，不排队保存业务写操作。本地 Server 仍可提供不依赖失联模型或远程服务的能力。 + +# 技术设计 + +## 1. 当前基线与相关工作 + +本提案核验的实现基线为 2026-09-04 的上游 `master`： +[`f0f288abecaccb97e1fe97d991b87b808bbebfbd`](https://github.com/oceanbase/powercontext/commit/f0f288abecaccb97e1fe97d991b87b808bbebfbd)。 +下表描述该基线已有的实现，不表示桌面产品已经发布： + +| 已有部分 | 可以复用的能力 | 与本提案相关的缺口 | +| --- | --- | --- | +| 公开 HTTP 契约 | Scope 与绑定、Memory、Source 摄取、Candidate、Skill、精确 Handoff 操作、统计和报告 | 没有桌面兼容性握手或持久 Handoff 投递收件箱契约 | +| Web UI | 总览、Skill、Review、Handoff Report 的 Jinja 模板和 JavaScript 模块 | 部分辅助路由位于 `/dashboard`；桌面业务访问必须使用公开 API | +| 原生服务层 | `service install`、`service status --json`、`service uninstall`；独立的用户级服务注册 | 尚无公开的 `service start/stop/restart --json` 接口 | +| 配置 | 不配置推理也可校验最小 Server 配置；模型能力可选 | 尚无桌面引导和受保护的配置编辑流程 | +| 认证 | 可选的部署级静态 Bearer 认证 | 此基线尚未实现资源级 Principal/角色授权 | +| 集成清单和诊断 | 随版本维护的能力声明与结构化集成检查 | 二者都不是实时 Handoff 接收端注册表 | +| 已发布软件包 | 已发布的 `0.1.0` 与开发中的 `master` 明确区分 | `0.1.0` 不包含原生 `service` 命令 | + +最新安装文档已经区分发布版本与未发布代码的安装路径。桌面必须选择在 manifest 中明确支持所需 runtime/service 契约 +的发行版本，或清楚标注锁定版本的预发布包。不能静默安装持续变化的 `master`，不能拼接不相关的集成和 runtime 版本， +也不能声称 `0.1.0` 已具备 service 能力。 + +| 依赖 | 基线时的状态 | 需要协调的内容 | +| --- | --- | --- | +| [RFC 1299](1299_local_server_availability_and_service_installation.md) | 服务架构及实现已进入 `master` | 保留唯一服务管理层和结构化状态语义 | +| [RFC 1345](1345_scope_organization_and_agent_integration.md) | Scope 模型及集成契约已具备 | 复用 Scope 身份、组织、绑定和显式发布 | +| [RFC 1396](1396_handoff_access_control.md)、实现 [#1398](https://github.com/oceanbase/powercontext/pull/1398) | RFC 已合并，实现 PR 仍开放 | 团队和资源共享验收依赖 Server 强制授权与授权后发现 | +| [#1419](https://github.com/oceanbase/powercontext/issues/1419) | Handoff 投递 Tracking Issue 仍开放 | 负责接收端登记、envelope、持久收件箱、投递状态、重试、过期和恢复 | +| [#1406](https://github.com/oceanbase/powercontext/issues/1406)、RFC [#1408](https://github.com/oceanbase/powercontext/pull/1408) | 安装 Tracking Issue 与 RFC PR 仍开放 | 负责 bootstrap、安装计划、组件安装、版本记录和恢复 | +| [#1405](https://github.com/oceanbase/powercontext/issues/1405)、RFC [#1410](https://github.com/oceanbase/powercontext/pull/1410) | 分发 Tracking Issue 与 RFC PR 仍开放 | 负责标准 Agent 发行物、target profile 和宿主配置规则 | +| [RFC 1400](1400_source_definition_and_observation_model.md) | Source 身份和观察模型设计已在仓库中 | 保持 Source 语义；连接器管理需要独立的受支持接口 | + +开放提案提供协调约束，不代表协议已经实现。最终由负责方确定的契约，优先于本文用于说明的名称。个人预览版可以先用 +已有的单部署能力；依赖通过验收之前，不能宣称已支持资源隔离的团队共享或可靠投递。 + +## 2. 组件职责与仓库位置 + +```text +可信 Web UI（共享展示和页面行为） + 浏览器适配器 ---------------------> 公开 Python Server HTTP API + 桌面适配器 -> 受限 Rust 桥接层 ------> 公开 Python Server HTTP API + | + +-> 系统凭据库、托盘、通知、文件选择器 + +-> 统一安装器和已有服务接口 + +操作系统服务管理器 -> 独立 Python Server -> 业务持久化和持久 worker +统一安装器 -> 已验证的 runtime/集成发行物与安装记录 +``` + +| 组件 | 负责 | 不应负责 | +| --- | --- | --- | +| 共享 Web UI | 导航、本地化展示、表单、受支持的用户操作 | 授权裁决、业务持久化、后台摄取 | +| Rust 桌面宿主 | 受限系统集成、受保护凭据访问、认证传输、有限本地偏好 | Memory/Handoff 语义、数据库访问、第二套安装器或服务监管器 | +| Python Server | 公开 API、Runtime 能力、业务校验、授权、持久化、持久处理 | 依赖桌面窗口保持打开 | +| 安装与分发层 | 发行物身份、bootstrap、安装计划、宿主配置、归属记录、升级恢复 | 桌面专属业务规则 | +| 已有服务层与系统管理器 | 用户级注册、服务身份、状态和生命周期 | 另一套争用相同端点的桌面守护进程 | + +在现有仓库中增加 `desktop/`，其中 `desktop/src-tauri/` 放 Tauri 宿主，另放桌面入口资源、打包配置和桌面验收工具。 +首次实现从已有 Web UI 中提取可复用的展示与传输边界。Server 托管的模板和静态资源继续位于 +`src/powercontext/server/`，继续随 Python wheel 分发。 + +桌面是独立构建的应用，可以引入自己的前端构建过程，但不能让 Python 包安装或现有 Server UI 运行依赖 Node、Rust +或桌面依赖。无需先迁移 React/Vue：在出现明确需求之前，现有 HTML、CSS 和 JavaScript 模块可以继续使用。生成的 +桌面入口标记应来自同一份共享源，并在发布前构建；安装后的桌面无需执行 Jinja 或连接 Server，就能显示安装和恢复页面。 + +Tauri capability、插件、依赖和锁文件需要审查并锁定。桌面专属 CI 与日常 Python 开发分开；修改共享 UI/API 时，仍须 +通过原有测试要求。 + +## 3. 公开 API 复用与兼容性 + +桌面是公开 API 的客户端，不能导入 Python Runtime 对象、打开业务数据库、抓取渲染后的 HTML，或依赖私有的 +`/dashboard/*` 辅助端点。共享页面通过传输适配器调用接口：浏览器使用 Web 部署的认证流程，桌面使用原生桥接层。 +页面代码不自行保存凭据或拼装路由。 + +已有 API 覆盖了初期管理的大部分操作： + +| 领域 | 已有公开接口 | 桌面实现要求 | +| --- | --- | --- | +| 健康和能力 | `/health/live`、`/health/ready`、`/v1/capabilities` | 区分进程存活、runtime 就绪、功能可用 | +| Scope | `/v1/scopes/*`、`/v1/scope-bindings/*`、Artifact 发布 API | 复用精确身份，以及支持的选择和绑定操作 | +| Memory | `/v1/memory/*` | 遵守大小限制、citation、修订冲突和已声明的搜索模式 | +| Review | `/v1/artifact-candidates/*` | 传递预期 Candidate 版本，显示冲突而非覆盖 | +| Skill 与 Experience | `/v1/skill/*`、`/v1/experience/*` | 保留受管生命周期、精确包引用和 Review 要求 | +| Handoff 与工作 | `/v1/handoff/*`、`/v1/work/*`、`/v1/handoff-reports/get` | 复用精确继续、确认接收、结果和只读报告 | +| Source | `/v1/sources/content`、Source 定义、观察、连接器 checkpoint | 使用受支持的摄取契约；checkpoint API 不是连接器管理面 | +| 统计 | `/v1/stats` | 使用 Server 授权的投影，不在客户端聚合未限制的记录 | + +缺失的公开投影必须先加入 `openapi/powercontext.yaml`，再运行 `make api-generate` 和 `make contract-test`，之后 +才可交付对应桌面功能。其他客户端也能使用相同路由和授权规则。本 RFC 本身不增加已实现的端点。 + +本提案建议新增受认证保护的 **`GET /v1/server-info`** 握手，初始契约包含 `schema_version`、`product`、持久化的 +不透明 `server_id`、`package_version`、`api_contract_version` 和版本化的 `feature_contracts`。这些字段描述部署 +身份和协议兼容性；运行时 provider 是否可用仍通过 `/v1/capabilities` 获取。该接口不能暴露文件路径、凭据、用户清单 +或未经授权的资源元数据。它遵守 Server 的认证策略，只提供认证客户端建立连接所需的最小元数据。 + +精确的 OpenAPI schema 和兼容性标识由 Server 负责，属于前置工作。每个桌面版本声明自己理解的契约版本和可选能力， +不能仅比较软件包版本字符串来判断兼容性。未知的可选能力可以忽略；必需契约不兼容时，阻止相关操作并解释升级要求。 +没有握手的旧 Server 应标记为“旧版/兼容性未知”，只提供明确测试过的支持，不能根据猜测版本开启功能。 + +`server_id` 是关联标识，不是归属或认证证明。凭据、经过验证的 TLS，以及核验过的本地安装/服务记录共同构成连接 +信任依据。Server 身份意外变化时，使待执行操作和缓存选择失效，要求用户明确重新连接。握手不能触发自动 runtime +升级、凭据转移或远程部署迁移。 + +## 4. 连接配置、传输与原生桥接 + +连接配置持久化本地不透明 profile ID、显示名称、规范化地址及受支持的 base path、连接模式、凭据引用、TLS 信任配置 +和已观察到的兼容信息，不保存业务记录。远程配置不能选择本地可执行文件或服务环境。 + +首版每个窗口只有一个活动连接，每个系统用户、每个发行通道只运行一个桌面实例。再次启动通过限定当前系统用户的原生 +IPC 激活已有实例，不额外开放 HTTP 管理监听端口。切换配置时递增连接 generation，取消未完成的读取，清理私有视图， +丢弃旧 generation 的迟到响应。已提交的写入始终关联原端点、Principal、Scope 和精确项，不能因切换连接而改投另一处。 + +传输层必须遵守现有客户端的 loopback 规则，包括 `tests/fixtures/transport_loopback_vectors.json` 中的公共用例： + +- 非 loopback 地址必须使用 HTTPS，并正常校验主机名与证书。允许现有客户端规则认可的 loopback HTTP；仅能访问 + loopback 并不能证明 Server 可信。 +- 拒绝地址中的用户信息、查询参数和 fragment，凭据不得放进 URL。保留受支持的 API base path，同时避免操作路径 + 逃逸该前缀。 +- 首版拒绝认证 API 请求重定向，不向其他主机、协议或端口转发凭据。如支持自定义 CA，只能显式绑定某个连接配置， + 不提供持久化的“关闭证书校验”开关。 +- 限制连接/读取超时、报文大小和分页，支持取消。分别呈现传输失败、证书失败、认证失败、无权访问、冲突、协议不兼容 + 和服务不可用。 +- 远程配置从提供凭据开始。公开健康检查成功不足以证明管理访问已通过认证；多用户使用还必须满足第 7 节资源授权契约。 + +Rust 在请求中注入所选凭据。WebView 只得到数据和安全错误，不提供读取凭据的 API。桥接命令限定为允许的公开操作 ID +及类型化参数、连接选择、只写凭据替换、有边界的文件选择/导入、诊断，以及支持的安装和服务操作。 + +不提供任意 `fetch(url)`、shell 执行、原始文件系统、终止进程或数据库桥接。渲染层不能自行决定可执行文件、命令行、 +发行源、目标路径或凭据请求头。原生侧独立校验所选连接、操作、参数、限制和当前操作上下文，不能只依赖 UI 按钮约束。 +文件操作使用系统选择的句柄或受限目标位置，不接受渲染层传入的任意路径。 + +只有随应用打包的本地 UI 文档拥有 Tauri capability。远程 Server 响应视为不可信数据，不在有原生权限的窗口中加载 +远程 HTML。使用严格 CSP，禁止远程脚本和不受限内联执行。以不可执行的方式安全渲染文本和支持的 Markdown；导入内容 +不能启动命令、加载远程图片、导航特权窗口，或通过嵌入标记调用 IPC。只有用户明确操作才在系统浏览器打开外部 HTTP(S) +链接；其他 URL scheme 需要单独审查并加入允许列表。 + +## 5. 本地服务生命周期与安装控制 + +本地 Server 保持 RFC 1299 的用户级身份：Linux 使用 systemd user service，macOS 使用 LaunchAgent，Windows +使用 Task Scheduler。桌面安装不请求 root、SYSTEM 或第二套机器级服务。服务配置仍只面向本地 loopback，来源于 +经过验证的本机安装环境。 + +已有结构化状态字段保持独立： + +| 字段 | 对桌面的含义 | +| --- | --- | +| `support` | 当前平台/环境是否支持原生服务注册 | +| `registration` | 注册是否存在、是否合法 | +| `definition` | 可执行文件和环境身份是否仍然有效 | +| `manager_ownership` | 系统管理器加载的条目是否属于 PowerContext | +| `manager` | active/inactive/failed/unknown 管理器状态 | +| `server_liveness` | 端点 live/unreachable/unknown | +| `endpoint`、`log_location`、`recovery_action` | 本地检查和恢复信息，按需脱敏展示 | + +`service status --json` 即使返回非零退出码，也可能包含合法的“不健康”结构化结果。应先解析约定结果，再判断是否 +执行失败。端点存活但归属 foreign 或 unknown，不代表受管安装健康。不能终止占用端口的进程、删除其他注册，或替换 +归属不明的可执行文件。 + +通过已有服务层使用 `service install` 的校准能力和 `service uninstall` 语义。如果产品需要显式启动、停止或重启， +必须先在该服务层补充操作和机器可读结果，当前 CLI 尚未提供。能力就绪前隐藏这些控制，并提供受支持的恢复入口， +不能用“卸载服务”实现“停止”。 + +桌面消费 #1406 及其安装 RFC 所负责的安装计划、核验后的组件结果和恢复语义。桌面管理安装的前提是提供版本化、 +非交互的机器接口。桌面不能另写安装引擎，也不能只凭退出码推断成功。特别是 #1408 提出的阶段和结构化输出，尚未 +定义公开的 `plan/apply/status` 命令或 JSON schema。 + +该接口需要提供可审查的计划、不可变组件身份、受影响位置、归属和兼容性检查、可观察进度、取消边界、持久操作身份、 +组件结果，以及客户端中断后的恢复能力。resolve/preflight 不修改安装；应用过期计划之前重新核验。并发操作锁和 +持久 journal 由安装器维护，不同入口不能竞争修改同一个安装。 + +Runtime 和各宿主组件可以分别成功。`uncertain` 必须先核验再重试；`installed` 不证明宿主已经加载成功。桌面如实 +展示负责方定义的 `unsupported`、`skipped`、`installed`、`current`、`stale`、`failed`、`uncertain` 状态， +不虚构跨多个独立宿主的全局原子回滚。 + +只有安装负责方支持持久执行和恢复时，关闭窗口才能让安装在后台继续。否则应用保留操作界面，只在安全边界提供取消。 +强制退出后必须能根据安装记录恢复，不能承诺普通 Tauri 子进程会在“退出”后继续运行。稳态 Python Server 始终由 +已有系统服务注册独立管理。 + +## 6. 凭据与本地配置 + +使用明确的系统凭据库适配器：首个 Windows 目标使用 Windows Credential Manager；macOS 和 Linux 验收时分别 +接入 Keychain、Secret Service。桌面偏好只保存不透明引用。凭据库不可用或锁定时，要求解锁、仅本次会话使用，或 +走另行支持的加密 vault 流程，不能静默回退明文存储。Tauri Stronghold 可以用于 vault，但它本身不是系统凭据库， +首个平台不以引入 Stronghold 为前提。 + +用户在可信配置表单输入或粘贴凭据时，凭据可以短暂存在于输入框和只写 IPC 参数中。提交后清空，不提供读回操作， +不保存到 WebView local/session storage、URL、命令行参数、日志、诊断、崩溃报告或通知。原生传输层在输出可观察 +错误前，清除 Authorization 头和敏感请求/响应字段。用户复制的 token 也可能留在系统剪贴板中；应用不声称能够抵御 +以相同用户身份运行的任意软件。 + +Server 的认证/provider secret 与桌面客户端凭据具有不同生命周期。独立 Server 必须能在桌面未运行、桌面 vault +未解锁时取得自己的配置。本地安装委托安装/服务配置负责方生成并校验配置、设置严格文件权限、处理环境身份，不能 +把凭据放入服务命令行。涉及已注册环境的配置变更，必须通过服务层校准流程生效。 + +发现过程只读取已知安装/服务记录及用户明确选择的配置文件，不扫描无关用户目录、不导入全部环境变量、不把 Server +或 provider 凭据复制到 UI 偏好。应用敏感配置修改前，展示作用范围及所需重启/校准操作。删除桌面连接时移除其凭据 +引用，并提供删除该凭据的选项；不能删除独立 Server 或 Agent 宿主仍在使用的凭据和环境文件。 + +## 7. 认证与资源授权 + +现有静态 Bearer 中间件建立的是部署级信任边界，并不提供团队角色或资源级共享。个人预览版可以明确以“共享信任” +模式连接这种部署。桌面管理的新本地安装默认应开启 Server 认证；连接已有未认证 loopback 部署时，展示其真实策略， +不静默修改它。 + +团队模式要求 Server 完成 RFC 1396 及相关实现规定的强制授权。可信 Principal 由 Server 解析；渲染层输入、Agent +名称、`receiver` 或接收方自报的授权检查都不能建立可信身份或授予权限。桌面不能通过隐藏按钮或先拉全量数据再过滤， +弥补后端授权缺失。 + +使用 Server 的当前 Principal 发现与受支持权限检查，解释哪些操作可用。它们仅辅助界面预检，每次读取正文、精确继续、 +确认接收、Review 或其他修改仍须经过 Server 当前授权检查。具体包括： + +- Scope 的组织关系不意味着权限继承或 Context 共享。 +- Candidate 读取和 Review 修改分别遵守读取与审查权限。 +- 获得某个已提交 Handoff revision 的授权，不等于能访问最新版本、相邻 revision、整个 Scope、报告或任意 Memory + 搜索。Evidence 遵守精确 citation manifest 及其授权规则。 +- Skill 发布同时保留资源和发布权限要求。target 标识是操作参数，不是新的授权资源或归属证明。 +- 集合、总数和搜索结果在 Repository 查询与分页之前完成授权过滤。如果无法安全过滤，明确失败，桌面不能回退到 + 无限制列表后再本地过滤。 + +缓存项、不透明列表游标、选择和通知元数据，按连接端点、当前 Principal 或凭据 generation，以及查询条件隔离。 +切换身份时清除旧私有状态，权限检查结果不能作为持久授权。凭据过期时停止受保护请求并提示重新认证；操作被拒绝时 +保留独立说明。两者都不能触发跨连接自动复用凭据或无限后台重试。 + +## 8. Scope、资产与 Review 行为 + +项目和工作流视图使用已有的不透明 Scope ID 和组织关系。仓库路径、分支、会话 ID、Agent 名称或显示标签都不是 +Scope 身份。Parent 组织关系不会产生传递性 Context reference、转移归属或发布 Artifact；跨 Scope 可见性和发布 +使用各自明确的已有 API。 + +观察选择（`all`、`subtree`、`exact`）与写入或集成绑定的精确目标 Scope 分开。表单显示目标 Scope，提交时固定 +该值；请求执行期间改变全局选择，不能重定向写操作。编辑绑定时显示受影响集成及其支持的选择语义，不假设所有宿主 +行为相同。 + +Memory 搜索使用 Server 支持的模式和限制，缺少 embedding/generation 能力只禁用相关操作。UI 保留 Memory +citation 和精确 Artifact reference，区分待处理 Source、Candidate、已提交 Artifact 和已退役项。不能把已接收 +的 Source 显示成已提取的 Memory，也不能把待 Review 的 Candidate 显示成已发布 Skill。 + +Review 复用 Candidate 的 expected-version 检查。冲突时重新加载权威 Candidate 并解释期间发生的变更，不静默 +批准更新版本。受管 Skill 生命周期变更保留 generation 检查，包发布使用已 Review 的精确包。下载、查看或发布包 +不授权桌面执行其中的脚本。 + +## 9. Handoff 发现、投递与操作 + +三个视图的用途不同： + +| 视图 | 权威来源 | 含义 | +| --- | --- | --- | +| Handoff Report | 已有报告 API | 所选 Scope 及其最新精确 Handoff 的只读投影 | +| 与我共享 | RFC 1396 的授权资源发现 | 当前 Principal 有权访问的精确资源身份 | +| Handoff 收件箱 | #1419 投递契约 | 接收方的持久投递记录，以及契约支持的状态和恢复 | + +授权列表的分页游标不是增量通知游标。授予访问权限不会投递 Handoff，也不代表未读。Candidate Review 和远程 Skill +receiver/reconciliation API 同样不能代替 Handoff 投递。桌面不另定义 envelope、接收端注册表、receipt 协议或 +重试调度器。 + +#1419 负责方需要提供所有消费者共用的投递契约：版本化 envelope 和精确引用、可信接收方关联、持久列表与恢复、 +去重身份、分页/事件游标语义、过期、取消，以及终态/可重试状态。桌面只消费这些不透明身份和受支持操作，并限定到 +当前端点与 Principal。实现完成前可以提供报告和授权发现，但必须明确标注持久投递收件箱不可用。 + +打开条目时使用原始精确 `ArtifactReference`，重新检查当前权限和投递状态，不能替换为 `latest`。条目不存在、 +过期、取消或权限撤销时，解释结果，不暴露缓存正文。只有某个精确 revision 的权限时，不能回退打开更广的 Scope 报告。 + +已有精确 Continue 和 Acknowledge 操作仍是权威语义。`accepted`、`needs_clarification`、`declined` 等 receipt +值保持原含义。接受需要接收方真实的 live-state、capability、authorization 观察；仅浏览桌面页面不能为另一个 +Agent 的环境作保证。只有受支持流程能够提供这些检查时，桌面才提供确认接收，否则引导至能完成检查的集成。 + +维护中的 Agent 宿主如果支持打开精确条目，就使用它声明的集成机制，只传递其接受的有界精确选择。否则提供受支持的 +复制/打开流程，不在 URL 中携带凭据或业务正文。桌面不虚构宿主 deep link，也不自行执行 Agent 任务。本地链接和 +通知激活仅用于导航：校验连接与条目的关联，不自动执行修改。 + +查看、标记已读（若支持）、投递成功、授予访问权限、接收方接受 receipt、记录 Task Outcome 是不同动作。界面分别 +命名；除非 Server 契约明确规定，不能把一种动作推进为另一种状态。 + +## 10. 通知与后台行为 + +Server 收件箱和 Candidate 状态是权威来源，系统通知只是尽力提示，不是持久队列，也不保证 exactly-once 投递。 +初期只订阅或轮询活动连接。有受支持增量契约时使用该契约；否则 Review 状态可以采用有上限、带退避的轮询。 +轮询 Candidate 列表只能得知当前待办，不能还原每个中间状态的完整历史。 + +通知消费要求如下： + +- 从负责方的稳定条目/事件身份和适用的精确 revision 派生通知身份。只持久化有界去重元数据和不透明游标；桌面通知 + 存储不保存 Memory、Source、Handoff、Prompt 或 Prepared Context 正文。 +- 使用负责方定义的恢复、游标过期和缺口修复语义。如果只有当前状态列表，就刷新该状态并展示摘要，不虚构漏收事件， + 不改变分页游标含义。 +- 按端点和 Principal 隔离元数据，凭据/身份变化时清理，并限制保留时间和容量。本地展示通知与 Server 标记已读、 + 确认接收是分开的操作。 +- 轮询支持抖动、退避、请求上限和取消；合并突发通知，抑制重复的离线/认证错误。凭据过期时停止受保护后台请求， + 提供一个有用的恢复提示。 +- 默认使用“PowerContext 有事项需要处理”这样的通用提示，只携带批准的有界元数据和本地不透明导航句柄。包括锁屏 + 场景在内，不显示正文、凭据、私有路径、敏感标题或未经处理的 Server 错误文本。 +- 点击后激活应用，明确恢复对应连接，并重新授权精确项。失效或伪造的激活句柄不能静默切换凭据或执行操作。 + +首次使用通知时解释用途并请求系统许可。拒绝许可后，应用内数量和收件箱仍可使用。首版完整退出桌面后不会继续通知， +下次启动时恢复 Server 当前状态。没有托盘支持时，普通窗口导航和退出仍须可用。验证真实安装包的通知与冷启动激活， +不能只测试进程内 mock。 + +## 11. Source、连接器与集成 + +首先支持显式输入文本，以及通过系统文件选择器导入有大小限制的 UTF-8 文本文件。传输前显示目标连接、Scope、计划 +使用的 Source 身份和大小。通过有边界的原生句柄读取所选文件，防止路径替换、目录穿越或链接变化后读取另一文件。 +Server 的内容大小限制和校验仍生效，不能静默扫描目录或用户主目录。 + +远程连接通过公开内容摄取契约传送用户确认的字节，本地路径不是远程 Server 可以直接打开的位置。保留 Source 身份、 +摘要和 provenance，避免不必要地泄露完整本地路径。重复导入遵守 Source 身份/冲突规则；不可变身份下内容发生变化， +不能被当成成功去重。 + +RFC 1400 的 Source 定义、观察和 checkpoint 不定义连接器发现、调度、provider 凭据或插件执行。首版连接器页面 +仅使用 Server 已支持的元数据和操作。新增管理 API 由连接器/Server 负责，必须形成公开契约后才交付对应控制。 +桌面关闭不能停止已接收的连接器任务；worker 凭据和 checkpoint 不能只存在桌面内。不完整抓取也不能被解释成未看到 +的内容已删除。 + +Agent 方面使用 #1405/#1410 维护的分发模型和随发行版本提供的能力声明。已有 `integrations/capabilities.toml` +是仓库版本契约，不是实时公开 HTTP capability API 或接收端目录。界面分别展示： + +1. 所选发行物声明自己在该宿主、平台和版本上支持什么。 +2. 安装器记录了什么已安装内容，以及由谁管理。 +3. 结构化诊断核验了哪些加载、连接、Scope 选择、capture 和 recall 行为。 +4. 只有相应负责方提供事实时，才显示运行状态或接收端登记状态。 + +使用 `doctor integrations --json` 等真实结构化诊断接口，不解析人类文本、不通过文件或工具数量推断健康。未支持 +或未观察的检查应明确标注。每个所选宿主由用户主动安装。配置合并、标准包身份、hook 行为和分发修复继续由原负责层 +实现，Rust 宿主不能复制这些规则，也不能自动改写所有检测到的 Agent 配置。 + +## 12. 离线、重试与并发变更 + +首版没有持久本地业务缓存或离线写队列。远程离线视图隐藏私有内容，显示连接状态；可选择保留尚未提交的表单输入， +但仅在内存中存在，并清楚显示未保存。重连时先刷新兼容性、身份、授权和所选资源状态，再开放修改。本地 Server +可以继续提供自己的离线能力；模型需要网络时，桌面不承诺离线生成。 + +读取重试有上限并可取消。修改重试遵循各操作公开契约。如果 Server 支持幂等键，同一逻辑操作重用同一个键。 +提交后超时意味着结果未知，不证明失败：重试前核验权威状态或提供检查入口。不能盲目重放 Review 批准、Handoff +receipt、导入、发布或安装。没有安全核验或幂等重试路径时，显示不确定状态，要求用户重新明确决定。 + +CLI、Agent、Web 和桌面并发修改都应正常工作。遵守已有 revision/version 检查，冲突时展示刷新后的条目，保留用户 +意图，但不静默应用到新 revision。待完成 UI 操作携带原连接/身份 generation 和精确目标，迟到结果不得出现在其他 +连接的页面上。 + +## 13. 分发、升级与恢复 + +首个 Windows 发行物使用签名的用户级安装包。本地 bootstrap 必须在未预装 Python、Rust、Node、Git 或编译器时 +工作。安装负责方提供所选系统和架构对应、经过验证的解释器/runtime 环境，以及维护中的集成发行物。仅远程连接的 +安装省略该 runtime。在线安装包和任何提供的离线包，都要声明包含哪些组件、仍需哪些网络访问。 + +当前服务实现会定位 Python 可执行文件，Windows 还要求相邻的 `pythonw.exe`，所以冻结后的 Python 可执行文件 +不能直接替换现有 runtime。优先使用安装器管理的版本化 Python 环境；未来采用冻结 runtime 时，需要单独完成服务 +兼容性和平台验收。Tauri sidecar 可以分发辅助程序，但不意味着 Server 生命周期由 Tauri 子进程接管。 + +发行计划分别记录桌面 UI/宿主版本、Python runtime 版本、API 契约版本、集成发行版本和持久数据兼容性。把便于人 +理解的通道解析成不可变 manifest，记录精确发行物位置、摘要、OS/架构和兼容性。发行信任需要绑定可信发布者的签名 +发行物或 manifest；仅从同一个不可信位置下载 checksum 不足以认证发行物。公钥和允许的更新源固定在任意渲染层或 +远程 Server 响应之外。 + +Tauri 签名 updater 可以更新桌面组件，但不会协调 Python 环境、Agent 配置、服务注册和数据库迁移。这些组件的 +共同计划属于统一安装器。桌面不能静默升级远程 Server，也不能自行覆盖被 Agent 共用的安装。 + +升级遵循以下规则： + +1. 解析并展示兼容的不可变版本、受影响组件、中断时间、数据兼容性和恢复方式，检查空间、归属、核验所需凭据，以及 + 是否有其他安装操作。 +2. 先校验发行物，再暂存到现有版本旁边，保留上次验证过的安装记录。下载或签名失败不影响仍在运行的安装。 +3. 切换 runtime 时，使用服务层支持的暂停处理、切换和校准路径。契约须明确进行中请求与持久任务如何处理，桌面不能 + 等待一个猜测的超时后直接杀进程。 +4. 完成就绪、兼容性和所选集成核验后，才将新安装记为健康。计划部分成功时分别报告组件结果。 +5. 只有安装器声明可安全回滚时，才回退可执行文件/配置。数据迁移属于 Server/runtime 负责方；旧 runtime 不能打开 + 不兼容的新数据。在不可逆迁移前，计划必须提供受支持备份/恢复或明确的向前修复路径，并由用户确认。 +6. 中断后重新读取持久操作记录，核验不确定组件，通过原负责方恢复或修复，不能推断中断操作已经成功回滚。 + +不能临时复制正在使用的数据库文件充当备份。备份、暂停处理和恢复必须符合实际持久化后端。负责层尚未支持的 schema +迁移或备份 API，会阻塞相应自动升级路径，不能转由 Rust 实现。 + +默认 stable 通道；预发布需要主动选择和明确标识。切换通道不能绕过数据或 API 兼容检查。首版提供升级提醒和用户 +明确执行的升级，不在活跃工作期间无人值守地升级 runtime。 + +## 14. 数据位置与卸载 + +| 数据或发行物 | 负责方 | 默认删除行为 | +| --- | --- | --- | +| 桌面可执行文件和打包 UI | 桌面包管理器/updater | 随应用卸载 | +| 连接、UI 偏好、有界通知元数据 | 桌面，位于独立用户级应用目录 | 可通过明确的重置选择删除 | +| 桌面凭据条目 | 系统凭据库 | 只删除所选连接/应用拥有的条目 | +| Python 环境、集成发行物、安装记录 | 统一安装器 | 仍有引用时保留，通过识别归属的计划删除 | +| 服务注册和受保护 Server 环境 | 已有服务/配置负责方 | 除非明确要求移除服务，否则保留 | +| Memory、Source、Artifact、调度状态、后端数据 | Server 持久化负责方 | 卸载应用或服务时默认保留 | +| Agent 宿主配置 | 分发/安装负责方与用户 | 只撤销自己拥有且记录过的修改，保留无关编辑 | + +Server 的 `POWERCONTEXT_HOME` 或已有平台数据目录规则继续生效，版本化应用目录不能成为业务数据目录。本地 +诊断页可以显示解析后的数据/日志位置，远程连接不能浏览 Server 文件系统。Rust 可以为用户打开已知本地位置，但 +不能读取或修改业务数据库内容。 + +“移除桌面应用”“移除本地服务”“删除 PowerContext 数据”是分别命名的操作。首版自动卸载器不提供数据删除；未来 +提供该 UI 时，需要负责方支持的明确流程，并确认精确的本地安装和数据路径。除非用户单独要求移除其他组件，否则 +卸载桌面后，独立安装的 Server 和 Agent 仍须可用。归属未知或被用户修改的文件应保留并解释，不能递归删除。 + +## 15. 诊断、隐私与安全范围 + +诊断汇总桌面版本/平台、已核验的安装/组件状态、服务事实、连接失败类别、支持的契约版本、安全 request ID，以及 +有界耗时/错误码。默认导出不包含 Memory、Source、Handoff、Prompt、Prepared Context、模型输出、凭据、 +Authorization 头、原始环境变量、连接查询参数或私有绝对路径。不能直接附上任意 Server 错误正文或完整 CLI +stdout/stderr，必须经过脱敏诊断模型归一化。 + +导出是本地、显式、可预览的操作，由用户选择脱敏文件的保存位置，不要求自动上传或产品遥测。崩溃上报默认关闭； +未来的主动开启机制也不能以“无正文诊断”为名传送内存转储或原始请求正文。日志保留时间和大小均有上限。 + +威胁模型包含恶意 Server 内容、导入文件、伪造通知/deep-link 激活、本地网站尝试访问桥接层、向错误端点泄露凭据， +以及发行物被篡改。防护来自可信本地 UI、受限 IPC、按连接隔离的传输、Server 授权、系统凭据库、安全渲染和可信分发。 +它不承诺抵御已被控制的操作系统、任意同用户恶意软件，或可访问用户进程和数据的管理员。 + +安全验收必须检查真实安装包的 capability/CSP、依赖权限、凭据库回退行为，以及发行物/升级验证。选择 Rust 本身 +不能证明这些边界正确。 + +## 16. 平台、无障碍与本地化 + +| 平台 | 建议交付状态 | 需要验收的问题 | +| --- | --- | --- | +| Windows 11 x64 | 首个正式验收目标，SQLite 本地 runtime | 用户级签名安装、WebView2 可用性/bootstrap、Credential Manager、Task Scheduler 归属、安装后通知、非 ASCII 路径 | +| macOS | 后续验收 | 不同架构 runtime、Keychain、LaunchAgent、签名/notarization、WKWebView 行为、通知许可 | +| Linux | 后续按明确发行版/桌面环境矩阵验收 | WebKitGTK/系统库、Secret Service、systemd 用户会话、托盘差异、打包和通知激活 | + +支持 Windows 不意味着支持 Windows ARM、Windows 上的 seekdb，或所有系统版本行为相同。Tauri 在三个目标上 +编译成功不足以证明产品支持。每个对外声明的 OS/架构，都必须在所声明环境通过安装包验收。 + +英文和中文 UI/文档同步维护。提供键盘导航、可见焦点、无障碍名称、屏幕阅读器语义、不会破坏 IME 输入的表单、高 +对比度，以及不只靠颜色表达的状态。通过滚动或响应式布局，管理流程在 800 × 600 窗口和 200% 缩放下仍可操作， +不能隐藏确认或恢复入口。保留用户选择的语言及系统主题偏好。 + +声明首个平台受支持前，在记录配置的参考机器上测量冷启动、空闲 CPU/唤醒次数、桌面与 runtime 的总内存、安装/下载 +体积，以及列表/搜索响应。架构验证后、功能扩展前确定发行预算。比较应包含 WebView2/runtime 依赖和 Python +Server，不能把较小的 Rust 可执行文件宣传成整个产品的占用。 + +## 17. 交付顺序与依赖门槛 + +拆成范围明确的实现 PR，关联本 RFC 和 #1428。复用已有依赖任务，不再创建重复的桌面 Tracking Issue，也不把整个 +产品塞进一个变更。 + +| 阶段 | 具体交付物 | 退出条件 | +| --- | --- | --- | +| P0：架构验证与契约 | Tauri 中打包可信共享页面；公开 API 传输；凭据适配器；Windows 安装后通知；连接/兼容设计；原型测量 | 确认 Windows 可行性和预算、安装/服务负责方的机器接口、公开 API 缺口、安全边界及发布负责人 | +| P1：个人预览 | 新旧本地安装、远程共享信任连接、服务状态/恢复、模型可选的首次 Memory 流程、所选 Agent 诊断、明确卸载行为 | 使用真实锁定发行物和当前支持的服务契约；不声称支持多用户资源共享或可靠 Handoff 投递 | +| P2：管理功能 | Scope/绑定视图、Memory/资产、Review、只读报告、显式 Source 导入、受支持连接器状态、双语无障碍、受保护诊断 | 保留公开 API 授权与版本冲突语义；准确展示受依赖限制的功能 | +| P3：授权协作 | 当前 Principal 资源发现、精确项权限、#1419 持久收件箱/恢复、受支持 Handoff 操作、有界通知 | RFC 1396 实现及 #1419 契约通过 Server 与桌面验收 | +| P4：首个平台正式发行 | 签名安装/升级发行物、恢复、完整首次使用流程、独立服务生命周期、保留数据的卸载 | 下列适用验收项在 Windows 11 x64 全部通过；发布兼容/支持矩阵并明确运维归属 | +| P5：增加平台 | 沿用相同边界的 macOS 和 Linux 包 | 每个声明支持的 OS/架构重复完成安装包验收 | + +P0/P1 无需等所有协作功能就绪，但不能用桌面自造 bootstrap 冒充统一安装。如果 #1406 机器接口或 Windows +bootstrap 不可用，预览版必须明确为“仅连接”，不能声称通过安装验收。个人预览版本身不代表完成 #1428。 + +关闭 #1428 时，建议维护者至少要求：一个正式验收的 OS，issue 要求的完整本地安装和管理流程，授权远程访问，可靠 +的 Server Handoff 收件箱消费，Review/Handoff 通知，以及文档规定的恢复和卸载保证。授权和投递负责方保留各自 +测试与发布责任；桌面验收验证这些能力组合后的完整流程。 + +## 18. 验收与验证 + +以下是可观察的验收要求，不要求固定内部函数调用、模块布局或 UI 元素 ID。使用公开 API 契约测试和真实安装后的 +桌面流程，只对宣称支持的平台要求相应平台测试。已有测试已保护的 Server 契约，应尽量复用。 + +| ID | 场景 | 必须观察到的结果 | +| --- | --- | --- | +| AC-01 | 无 Python/Node/Rust/Git 的干净环境首次安装，且不配置模型 | 核验本地 runtime/service 与所选维护中集成的安装；显式 Memory 保存和全文召回成功；依赖模型的操作说明条件 | +| AC-02 | 已有手工服务、过期受管定义、端口占用或其他服务注册 | 正确区分状态，保留归属未知的服务/数据，只提供受支持修复 | +| AC-03 | 关闭窗口、退出、重启桌面、重启系统用户会话 | 独立服务和已接收持久任务不因桌面退出而丢失；登录行为符合各自设置 | +| AC-04 | 下载/安装/升级中断，或签名/就绪检查失败 | 尽可能保留原可用状态；组件结果和不确定性明确；受支持恢复/回滚遵守数据兼容性 | +| AC-05 | 旧 runtime、不兼容 API、混合集成版本或 Server 身份变化 | 解释能力/兼容限制；不猜测支持、不静默改投目标、不自动升级远程 Server | +| AC-06 | loopback、非 loopback HTTP、错误 TLS、重定向、凭据过期和授权拒绝 | 保持现有传输策略，不跨端点转发凭据，各失败类别可区分 | +| AC-07 | 请求或通知未完成时切换连接/Principal | 旧身份的数据、游标、响应、凭据和修改目标不出现在新连接 | +| AC-08 | Principal 只能读某个精确 Handoff revision | 不泄露 latest/相邻 revision、未授权 evidence、更广报告或 Scope 内容；操作重新授权 | +| AC-09 | 受限制列表及 Review/发布权限 | Server 在分页/总数之前过滤；不安全过滤失败；隐藏按钮不能绕过授权；各权限对应操作正确 | +| AC-10 | Candidate/资产并发更新，或修改请求超时导致结果未知 | 显示版本冲突或未知结果；不静默批准新 revision，不盲目重复修改 | +| AC-11 | 断线期间收到 Handoff、游标过期、权限撤销或投递取消 | 按负责方语义恢复授权收件箱；保留原精确引用；导航不会自动确认接收 | +| AC-12 | 安装后通知、拒绝许可、突发事项、完整退出或过期激活句柄 | 有界无正文提示、去重合并、安全精确导航、应用内回退可用，并准确说明后台限制 | +| AC-13 | 文件导入、重复 Source 身份、字节变化、不完整抓取或摄取时关闭桌面 | 确认内容通过公开 API 到达所选 Scope；保留身份/冲突规则；不静默扩大导入、删除或由桌面运行 worker | +| AC-14 | 恶意 HTML/Markdown、任意 IPC 参数、伪造链接或错误连接端点 | 无任意执行/文件系统访问、凭据读回、特权远程导航或意外修改 | +| AC-15 | 在 token、路径、provider 配置、错误和业务正文中植入秘密测试标记 | 通知、普通日志、诊断导出、URL、渲染层持久存储和发行遥测中均无标记 | +| AC-16 | 移除桌面、移除服务或遇到用户修改的集成文件 | 默认保留数据；未单独移除的独立组件仍可用；保留未知/非己方文件 | +| AC-17 | 中英文、纯键盘、IME、屏幕阅读器、高对比度、小窗口和 200% 缩放 | 安装、连接、Review、通知导航、恢复和卸载选项仍易懂且可操作 | +| AC-18 | 在参考机器及声明的 OS/架构安装正式发行物 | 签名发行物和升级路径可用；完整占用和响应测量达到约定预算 | + +修改公开契约的实现 PR 运行 `make api-generate` 和 `make contract-test`，保留正常 `make check`、相关行为 +测试和严格文档检查。共享 UI 修改需要 Web 与桌面行为覆盖；桌面打包修改需要安装包冒烟测试，服务修改复用服务层 +原生平台测试。仅有 mock 传输测试不能证明安装或系统通知合格。 + +# 缺点 + +这会给 Python 项目增加一个长期维护的原生应用、Rust 工具链、桌面 JavaScript 打包、签名发布流程和系统专项测试。 +共享 UI 可以减少重复展示逻辑，但提取传输和构建边界仍需投入，也可能影响已有 Web UI。 + +Tauri 在不同系统使用不同 WebView，渲染、无障碍、认证集成和原生通知都需要逐平台验证。Python 及可选存储/模型 +依赖可能占据大部分包体积和运行资源，减小桌面宿主后获得的实际收益未必很大。 + +独立 runtime 安装比单个可执行文件更复杂。它符合现有 Server 在桌面关闭后继续服务 Agent 的职责，但需要协调 +兼容性和恢复。完整协作产品还依赖本 RFC 实现范围之外的授权和投递工作。 + +# 设计理由与替代方案 + +## Tauri 2 与 Electron + +| 考虑项 | Tauri 2 | Electron | 对 PowerContext 的判断 | +| --- | --- | --- | --- | +| Web UI 复用 | 在系统 WebView 中运行 HTML/CSS/JavaScript | 在随包 Chromium 中运行 HTML/CSS/JavaScript | 两者都能复用管理 UI，都不要求重写业务代码 | +| 原生宿主 | Rust 宿主，显式授权 capability/插件 | Node.js 主进程，受限 preload/IPC | 范围较小的 Rust 宿主符合桌面职责和贡献者偏好 | +| 分发占用 | 复用系统 WebView，但有平台 bootstrap 依赖 | 自带 Chromium 和 Node.js | 倾向 Tauri，但测量必须包含 Python/WebView/runtime 的完整发行物 | +| 跨平台渲染 | 存在 WebView2、WKWebView、WebKitGTK 差异 | 自带 Chromium，相对一致 | 系统 WebView 无法满足必需无障碍/UI 行为时，Electron 更有优势 | +| Python 集成 | 外部 runtime 或辅助进程 | 外部 runtime 或辅助进程 | 两者都不解决 Python 安装、服务归属和业务 schema 迁移 | +| 凭据与升级 | 需要明确接入凭据库并设计组件升级 | 原生加密/升级能力仍需要策略和集成 | 两者都不替代系统凭据库验收、授权或安装契约 | +| 团队成本 | Rust/原生插件维护能力和平台验收 | JavaScript/TypeScript 生态与 Electron 经验 | P0 验证 Rust 维护和发布归属 | + +选择 **Tauri 2**，因为产品是在既有 Python Server 和相对轻量的 Web 管理界面外增加原生控制能力，宿主可以保持 +较小职责，不需要 Node.js 插件、自带浏览器引擎或桌面本地 AI 执行。Rust 用于系统集成和受限传输，不以性能为理由 +重写 Python 业务逻辑。 + +如果 P0 发现系统 WebView 的无障碍/渲染、必需原生集成，或持续 Rust/平台维护存在实际阻塞，Electron 是备选。 +切换时保持相同公开 API、安装、服务和授权边界。不并行维护两套正式桌面外壳，也不在比较完整安装原型之前声称某种 +方案性能更好。 + +## 其他方案 + +- **只做 Web UI：** 继续支持，对远程管理成本最低，但无法完成原生安装/服务诊断、系统凭据保存、文件集成和安装后通知流程。 +- **在有原生权限的外壳中直接加载 Server 页面：** 减少早期 UI 提取工作，但让安装依赖 Server 已可用，并把远程标记 + 放到原生权限旁边，因此选择打包可信本地 UI。 +- **让 Python 成为桌面子进程：** 可用于原型，但关闭/升级桌面不能中断 Agent 或持久工作，因此保留已有独立服务管理。 +- **用 Rust 重写 Runtime/存储：** 重复成熟业务契约和迁移责任，当前桌面需求没有要求这样做，不属于本提案。 +- **完全使用 Rust 原生控件：** 无法复用已有 Web 展示，又产生一套管理界面。只有明确证明共享 Web UI 无法满足需求时 + 再考虑。 + +# 相关设计与参考 + +项目内基础包括 RFC +[1299](1299_local_server_availability_and_service_installation.md)、 +[1345](1345_scope_organization_and_agent_integration.md)、 +[1396](1396_handoff_access_control.md)、 +[1400](1400_source_definition_and_observation_model.md)、 +[1351](1351_standard_skill_package_lifecycle.md)，以及 +[Server Web UI 开发指南](../development/server-web-ui.md)。前面的依赖表区分了已实现部分和开放中的安装、分发、 +授权、投递工作。 + +以下官方资料用于判断框架和打包方案，其中的机制不能替代 PowerContext 的组件契约： + +- [Tauri 架构](https://v2.tauri.app/concept/architecture/)与 + [WebView 版本](https://v2.tauri.app/reference/webview-versions/)说明宿主/UI 模型和平台引擎。 +- [Tauri capability](https://v2.tauri.app/security/capabilities/)与 + [CSP](https://v2.tauri.app/security/csp/)用于设计受限原生桥接和可信打包 UI。 +- [Tauri sidecar](https://v2.tauri.app/develop/sidecar/)、 + [updater](https://v2.tauri.app/plugin/updater/)和 + [通知](https://v2.tauri.app/plugin/notification/)提供组件机制，仍需验证生命周期和真实安装行为。 +- [Tauri Windows 分发](https://v2.tauri.app/distribute/windows-installer/)、 + [macOS 签名](https://v2.tauri.app/distribute/sign/macos/)及 + [AppImage 分发](https://v2.tauri.app/distribute/appimage/)说明各系统不同的交付要求。 +- [Tauri Stronghold](https://v2.tauri.app/plugin/stronghold/)描述 vault 能力；本提案单独选择系统凭据库适配器。 +- [Electron 文档](https://www.electronjs.org/docs/latest/)、 + [安全指南](https://www.electronjs.org/docs/latest/tutorial/security)、 + [safeStorage](https://www.electronjs.org/docs/latest/api/safe-storage)与 + [autoUpdater](https://www.electronjs.org/docs/latest/api/auto-updater)用于评估替代方案。 + +# 待解决问题 + +在 RFC 审查或指定阶段，解决以下跨负责方决策，不把核心业务语义交给桌面： + +1. **RFC 接受前：** 确认 Windows 11 x64 首个平台、Tauri 维护/发布负责人，以及个人预览和完成 #1428 的阶段区别。 +2. **桌面管理安装前：** 确定安装/服务机器接口和 Windows bootstrap 时间。#1406 要求 shell 和 PowerShell 同为 + 首批入口，而开放的 #1408 仍未确定引擎及 PowerShell 时序；本提案不选择安装引擎语言，也不虚构 CLI 参数。 +3. **依赖兼容性的管理功能前：** 与 Server 负责方确定 `server-info` schema、契约版本策略、稳定 Server 身份的 + 生命周期和支持窗口。 +4. **协作版本发布前：** 与 #1419 确定投递/收件箱契约、集成启动及接收方检查，并完成 RFC 1396 实现的授权验收。 + 不将授权列表分页视为事件重放。 +5. **P0 结束时：** 公布实测性能预算、代码签名/更新密钥归属、发布 CI 环境及依赖/安全维护策略。这些是发布前提， + 不表示当前已经覆盖。 + +连接器管理面、更多认证方式、高级离线同步和广泛 Agent 执行属于其他设计，不能通过桌面私有协议掩盖这些能力缺失。 + +# 未来可能性 + +首个平台完成全部验收后，再增加 macOS/Linux 包、更多架构，以及用户明确开启的多连接后台通知。后续可以扩展 +Source 导入格式、受支持的连接器配置，或在 Server 契约具备后接入系统浏览器认证。 + +离线写队列、本地业务缓存、更广的 Agent 操作或云同步都会引入新的一致性和安全责任，需要单独提案；采用本 RFC +不以它们为前提。 diff --git a/zensical.toml b/zensical.toml index d1ee08e22..9fb285d95 100644 --- a/zensical.toml +++ b/zensical.toml @@ -78,6 +78,7 @@ nav = [ { "RFCs & Meetings" = [ { "RFCs" = [ { "Overview" = "en/rfcs/README.md" }, + { "Desktop Control Center (proposal)" = "en/rfcs/0000-desktop-control-center.md" }, { "1400 Source Definition and Observation Model" = "en/rfcs/1400_source_definition_and_observation_model.md" }, { "1345 Scope Organization and Agent Integration" = "en/rfcs/1345_scope_organization_and_agent_integration.md" }, { "1229 Unified Workloads and Long-Horizon Memory Evaluation" = "en/rfcs/1229_unified_workloads_and_long_horizon_memory_evaluation.md" }, @@ -177,6 +178,7 @@ nav = [ { "RFC 与会议纪要" = [ { "RFC" = [ { "概览" = "zh/rfcs/README.md" }, + { "桌面控制中心（提案）" = "zh/rfcs/0000-desktop-control-center.md" }, { "1400 Source 定义与观察模型" = "zh/rfcs/1400_source_definition_and_observation_model.md" }, { "1345 Scope 组织与 Agent 集成" = "zh/rfcs/1345_scope_organization_and_agent_integration.md" }, { "1229 统一工作负载与长程 Memory 评估" = "zh/rfcs/1229_unified_workloads_and_long_horizon_memory_evaluation.md" }, From acdc04d31932e0031adb67d2ea510412f777f746 Mon Sep 17 00:00:00 2001 From: knqiufan Date: Fri, 4 Sep 2026 17:26:21 +0800 Subject: [PATCH 2/2] docs(rfc): assign desktop proposal number 1455 --- ...sktop-control-center.md => 1455-desktop-control-center.md} | 2 +- ...sktop-control-center.md => 1455-desktop-control-center.md} | 2 +- zensical.toml | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename docs/en/rfcs/{0000-desktop-control-center.md => 1455-desktop-control-center.md} (99%) rename docs/zh/rfcs/{0000-desktop-control-center.md => 1455-desktop-control-center.md} (99%) diff --git a/docs/en/rfcs/0000-desktop-control-center.md b/docs/en/rfcs/1455-desktop-control-center.md similarity index 99% rename from docs/en/rfcs/0000-desktop-control-center.md rename to docs/en/rfcs/1455-desktop-control-center.md index 30b5e5952..802e7245d 100644 --- a/docs/en/rfcs/0000-desktop-control-center.md +++ b/docs/en/rfcs/1455-desktop-control-center.md @@ -1,6 +1,6 @@ - Proposal Name: `desktop_control_center` - Start Date: 2026-09-04 -- RFC PR: Not opened +- RFC PR: [oceanbase/powercontext#1455](https://github.com/oceanbase/powercontext/pull/1455) - Tracking Issue: [oceanbase/powercontext#1428](https://github.com/oceanbase/powercontext/issues/1428) - Status: Proposed diff --git a/docs/zh/rfcs/0000-desktop-control-center.md b/docs/zh/rfcs/1455-desktop-control-center.md similarity index 99% rename from docs/zh/rfcs/0000-desktop-control-center.md rename to docs/zh/rfcs/1455-desktop-control-center.md index 317fa4e8e..3476b972c 100644 --- a/docs/zh/rfcs/0000-desktop-control-center.md +++ b/docs/zh/rfcs/1455-desktop-control-center.md @@ -1,6 +1,6 @@ - 提案名称：`desktop_control_center` - 开始日期：2026-09-04 -- RFC PR：尚未创建 +- RFC PR：[oceanbase/powercontext#1455](https://github.com/oceanbase/powercontext/pull/1455) - Tracking Issue：[oceanbase/powercontext#1428](https://github.com/oceanbase/powercontext/issues/1428) - 状态：提案 diff --git a/zensical.toml b/zensical.toml index 9fb285d95..436dd9743 100644 --- a/zensical.toml +++ b/zensical.toml @@ -78,7 +78,7 @@ nav = [ { "RFCs & Meetings" = [ { "RFCs" = [ { "Overview" = "en/rfcs/README.md" }, - { "Desktop Control Center (proposal)" = "en/rfcs/0000-desktop-control-center.md" }, + { "1455 Desktop Control Center" = "en/rfcs/1455-desktop-control-center.md" }, { "1400 Source Definition and Observation Model" = "en/rfcs/1400_source_definition_and_observation_model.md" }, { "1345 Scope Organization and Agent Integration" = "en/rfcs/1345_scope_organization_and_agent_integration.md" }, { "1229 Unified Workloads and Long-Horizon Memory Evaluation" = "en/rfcs/1229_unified_workloads_and_long_horizon_memory_evaluation.md" }, @@ -178,7 +178,7 @@ nav = [ { "RFC 与会议纪要" = [ { "RFC" = [ { "概览" = "zh/rfcs/README.md" }, - { "桌面控制中心（提案）" = "zh/rfcs/0000-desktop-control-center.md" }, + { "1455 桌面控制中心" = "zh/rfcs/1455-desktop-control-center.md" }, { "1400 Source 定义与观察模型" = "zh/rfcs/1400_source_definition_and_observation_model.md" }, { "1345 Scope 组织与 Agent 集成" = "zh/rfcs/1345_scope_organization_and_agent_integration.md" }, { "1229 统一工作负载与长程 Memory 评估" = "zh/rfcs/1229_unified_workloads_and_long_horizon_memory_evaluation.md" },