源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

docs/architecture/project-structure.md

@@ -0,0 +1,529 @@
+# Project Structure
+
+This document defines the current repository structure for `tutti`.
+
+It explains what belongs in each top-level area and how new directories should be introduced.
+
+## Top-Level Layout
+
+```text
+tutti/
+  apps/
+  config/
+  services/
+  packages/
+  tools/
+  docs/
+```
+
+## Top-Level Responsibilities
+
+### `apps/`
+
+`apps/` contains product entrypoints and user-facing shells.
+
+Current area:
+
+- `apps/cli`: bundled terminal entrypoint for the local daemon capability protocol
+- `apps/desktop`: Electron desktop application
+
+Rules:
+
+- app directories may own presentation, runtime integration, and entrypoint-specific behavior
+- app directories must not duplicate business logic already owned by `services/`
+- do not materialize future app ideas as empty directories; keep them in docs until the module has a real interface and implementation
+
+### `services/`
+
+`services/` contains long-running product backends.
+
+Current area:
+
+- `services/tuttid`: local daemon and primary business core
+
+Rules:
+
+- service directories own business workflows, durable state, and persistence ownership
+- if a feature requires domain decisions or state transitions, it should usually land in `services/tuttid`
+
+### `config/`
+
+`config/` contains repository-owned default sources that are consumed by generation or tooling.
+
+Current area:
+
+- `config/tutti.defaults.json`: single-source default names and budgets for local state, transport, and logging
+
+Rules:
+
+- keep `config/` focused on repository defaults, not per-user settings or secrets
+- prefer generating runtime-specific code from `config/` rather than reading these files ad hoc inside packaged applications
+- do not turn `config/` into a second `docs/` directory; only keep machine-consumable sources here
+
+### `packages/`
+
+`packages/` contains shared boundaries, not default implementation code.
+
+Current grouping:
+
+```text
+packages/
+  browser/
+  clients/
+  configs/
+  connector/
+  device-link/
+  events/
+  ui/
+  workbench/
+  workspace/
+```
+
+Rules:
+
+- organize packages by responsibility, not by language alone
+- use `clients/*` for domain-specific client access
+- use `device-link` for shared ICE/QUIC peer transport, product-neutral Relay stream mechanics, and the gomobile boundary consumed by Tutti, TSH, and mobile clients
+- use `events/*` for schema-first shared business event protocol contracts, validators, and generated transport metadata that multiple hosts consume
+- use `browser/*` for reusable browser/workbench node mechanics that are shared by desktop hosts without carrying product-specific bridge methods
+- use `configs/*` for shared engineering configuration
+- use `ui/*` for shared frontend foundation packages such as visual-system boundaries, host-agnostic React hooks, and host-agnostic i18n runtime support
+- use `workbench/*` for the shared workbench snapshot contract and reusable workbench interaction surface intended to be shared by the open-source desktop and TSH
+- use `workspace/*` for narrow reusable workspace-domain contracts and feature surfaces intended to be shared by the open-source desktop, TSH, and TACH
+- do not create vague packages such as `shared`, `common`, or `client-sdk`
+- do not pre-create package directories for future domains; add the package only when a real multi-consumer seam exists
+- documentation alone does not make a package seam real; the package must expose
+  a narrow interface that a current consumer can use without learning its
+  implementation layout
+
+### `tools/`
+
+`tools/` contains repository support code such as:
+
+- build helpers
+- packaging helpers
+- generation entrypoints
+- validation or maintenance scripts
+
+Core product behavior should not permanently live in ad hoc scripts when it belongs in a first-class application or service.
+
+### `docs/`
+
+`docs/` contains persistent repository documentation.
+
+Current sub-areas:
+
+- `docs/architecture`: structure notes and technical design context
+- `docs/conventions`: coding, layering, naming, and storage rules
+
+Rules:
+
+- `docs/architecture` and `docs/conventions` are the long-lived source of truth
+- temporary planning notes should not become the primary source of current repository rules
+- once a design has landed and stabilized, durable rules should be promoted into `docs/architecture` or `docs/conventions`
+
+## Current Structure Decisions
+
+### `apps/cli`
+
+`apps/cli` is responsible for:
+
+- terminal argument parsing
+- local daemon endpoint discovery and bearer authentication
+- invoking the daemon-owned CLI capability protocol
+- rendering daemon command output for terminal users
+
+It must not become a second business core. Command metadata, workspace resolution, edition/context filtering, and command execution stay in `services/tuttid`.
+
+### `apps/desktop`
+
+`apps/desktop` is responsible for:
+
+- renderer UI
+- Electron main-process lifecycle
+- preload bridge and IPC exposure
+- native desktop integration
+- supervising `tuttid`
+
+It must not become a second business core.
+
+Desktop keeps four top-level source areas:
+
+```text
+apps/desktop/src/
+  main/
+  preload/
+  renderer/
+  shared/
+```
+
+Desktop summary:
+
+- `main/` owns Electron lifecycle, daemon/runtime composition, host access, transport, IPC, update integration, and window creation
+- `preload/` owns the typed bridge surface exposed to renderer
+- `renderer/src/app/windows/*` owns renderer window composition shells such as `dashboard` and `workspace`
+- `renderer/src/features/*` owns reusable renderer feature modules
+- `renderer/src/features/*/services/*` owns feature service public surfaces, while `services/internal/**` stays private to the owning feature
+- `renderer` consumes shared visual foundations from `packages/ui/system` instead of growing its own token or primitive layer
+- `shared/` stays narrow and desktop-local
+- desktop-owned i18n resources stay under `shared/i18n/*`, while reusable package default i18n resources stay with the owning package and are merged by the renderer app-level i18n runtime
+- `main/bootstrap.ts` stays a top-level coordinator; service assembly belongs in `desktopAppServices.ts`, `desktopDaemonRuntime.ts`, `desktopHostServices.ts`, and `desktopAppLifecycle.ts`
+
+The authoritative desktop directory shape and ownership rules live in [docs/conventions/desktop-layering.md](../conventions/desktop-layering.md). Keep this repository-level document as a summary, not a second full desktop structure spec.
+
+### `packages/desktop/*`
+
+Desktop packages own product-neutral lifecycle and native-host integration
+mechanics shared by more than one desktop product.
+
+Current packages:
+
+- `packages/desktop/update-admission`: minimum-version policy contracts,
+  validation, mandatory updater ownership, Electron admission lifecycle,
+  capability-minimal preload API, shared React presentation, and default i18n
+
+Product policy transport, normal update preferences, release feeds, download
+URLs, window assets, logging sinks, and business-window enumeration remain in
+the consuming desktop app.
+
+### `packages/connector/*`
+
+Connector packages own host-neutral connector domain boundaries shared across
+desktop daemons.
+
+Current owners:
+
+- `packages/connector/contracts`: versioned authorization wire contracts and
+  the local OpenAPI fragment
+- `packages/connector/daemon/core`: connector catalog, installation, authorization,
+  compatibility, operation, and recovery application core
+- `packages/connector/daemon/application`: reusable daemon lifecycle and workers
+- `packages/connector/daemon/adapters/sqlite`: canonical local persistence and outbox
+- `packages/connector/daemon/adapters/controlplane`: account-scoped authorization
+  HTTP and realtime protocol adapter
+- `packages/connector/runtime`: latest-only artifact caching, no-network archive
+  import, same-machine composition, managed-runtime installation primitives,
+  Connector route/MCP registries, and the session-bound loopback MCP server
+- `packages/connector/renderer`: React-free frontend application services plus
+  the only shared Connector-specific React and i18n owner
+
+Remote endpoint authentication, credentials, state-root selection, generated
+daemon clients, product command publication, and OS process integration remain
+in host adapters.
+
+### `services/tuttid`
+
+`services/tuttid` is the primary business core.
+
+It owns:
+
+- business rules
+- domain workflows
+- local persistence
+- long-running daemon behavior
+
+### `packages/clients/*`
+
+Client packages provide domain-specific access helpers for consumers.
+
+They should remain focused, named by responsibility, and free of hidden business rules.
+
+`packages/connector/daemon/adapters/controlplane` is the shared Go protocol client for
+account-scoped Connector authorization. It owns authorization session,
+snapshot, and realtime-event decoding plus bounded HTTPS transport. A product
+host supplies the API prefix, HTTP client, and per-account request authorizer;
+the package never stores account cookies, chooses an environment, or sends
+credentials to a runtime VM. `packages/connector/daemon/core` selects this client only
+for `remote_streamable_http` releases, while `managed_stdio` authorization
+stays with the injected local implementation host.
+
+`packages/clients/device-authority-go` is the shared Go client boundary for the
+Device Authority owner lifecycle across Tutti and TSH. The initial package is a
+staged cross-repository extraction from TSH: publish the stable module first,
+then refactor TSH to the released version without changing behavior, then wire
+the same client into Tutti. This ordering is required because cross-repository
+consumers must not use workspace replacements or pseudo-versions. The package
+owns the control-plane wire contract, canonical Ed25519 enrollment and
+owner-token signing, bounded HTTP response semantics, and credential-binding
+validation. Product adapters still own base-URL and API-prefix selection,
+account/session/device headers, durable identity storage, Relay demand and lease
+scheduling, logging, and retry policy. The client must not infer
+local-versus-remote deployment policy or import Relay transport lifecycle code.
+
+`packages/clients/market-go` is the market-neutral generated Go client boundary
+for TSH Market. It pins the provider-generated protobuf and HTTP artifacts to an
+exact `tsh-server` commit and SHA-256 values without importing the server
+application module or copying the remote schema into Tutti's local OpenAPI.
+The update tool verifies the source checkout commit before copying digest-matched
+files. Product adapters inject the HTTP transport, gateway base path, and request
+authorization. Connector consumers pass `itemType=connector`; future Skill
+consumers reuse the same client with `itemType=skill`.
+
+### `packages/device-link`
+
+DeviceLink is the shared Go peer-transport boundary for Tutti Desktop, TSH
+Desktop, and mobile clients. It owns ICE candidate negotiation, QUIC over the
+selected packet path, mutual ephemeral certificate pinning, categorical path
+classification, the gomobile build surface, and product-neutral authenticated
+link lifecycle mechanics: generation-fenced admission, establishment
+serialization, pooled stream ownership, connection racing, and annealed path
+probing. It also owns generic Relay byte-stream dialing and the reusable
+reference-counted WebSocket/yamux owner-tunnel mechanics, including liveness,
+readiness ordering, reconnect backoff, stream dispatch, and close ordering.
+
+Its `candidateexchange` subpackage also owns the Trickle ICE application
+mechanics shared by Go and gomobile consumers: immediate credential snapshots,
+candidate change coalescing, acknowledgement-bound exact-snapshot publication
+retry, gathering completion, and push-hint plus authoritative-poll remote
+refresh. Consumers provide rendezvous callbacks or execute facade actions and
+retain product retry classification; account authorization, attempt state,
+request signing, room/pairing semantics, and wire DTOs stay in their product
+adapter. The callback-free Go `ActionPump` owns both candidate workers and
+allows at most one unresolved action per worker, so a slow rendezvous read does
+not block local publication. The gomobile facade exports scalar/JSON start,
+next-action, resolve-action, notify, and stop/cancel operations. Mobile uses two
+identical action drainers to execute signed authoritative reads/writes without
+reimplementing ICE retry timing, wake cursors, polling, or worker cancellation
+in TypeScript, Kotlin, or Objective-C.
+
+It exposes authenticated bidirectional streams and generic Relay byte streams,
+and must remain independent of Agent, Session, Workspace, account, pairing,
+rendezvous, Relay authorization, and Relay product policy. Peer and owner keys
+stay opaque; host services and apps inject path dialers, credentials, leases,
+fallback timing, and application stream protocols. The `tuttid` Mobile Remote
+owner is the first adapter for the shared link manager; its pairing and Agent
+framing remain service-owned. TSH remains the product authority for its Relay
+registration and lease lifecycle even when it consumes the shared owner-tunnel
+mechanics. Raw addresses, candidates, credentials, and payloads must not enter
+ordinary logs or metrics.
+
+### `packages/events/*`
+
+Event packages define shared business event protocol boundaries.
+
+Current package:
+
+- `packages/events/protocol`: repository-owned JSON Schema and event-definition source files for the business event stream, plus generated TypeScript protocol contracts and daemon transport registry output
+
+Rules:
+
+- keep schema-first source files in the package and keep those files as the only shared source of truth for business event topics
+- keep generated TypeScript exports narrow and protocol-oriented
+- keep WebSocket lifecycle management, daemon orchestration, and renderer feature behavior outside `events/*`
+
+### `packages/browser/*`
+
+Browser packages define reusable Browser Node mechanics for hosts that need to
+embed web content in the shared Workbench.
+
+Current packages:
+
+- `packages/browser/workbench-node`: `@tutti-os/browser-node`, the shared
+  Workbench Browser Node package. It owns generic HTTP/HTTPS navigation,
+  session partition resolution, runtime state, bridge shape, Electron webview
+  guest management, and package-local i18n defaults. Host adapters own product
+  globals, backend-token access, preview proxy behavior, and business bridge
+  methods.
+
+Rules:
+
+- keep Browser Node mechanics in this package and host/product-specific methods
+  in the consuming app or integration
+- require hosts to provide bridge namespaces; the package must not assume
+  `__tutti`, `__tsh`, or any other product global
+- keep preview proxy interfaces inert until a host intentionally implements
+  route resolution
+- keep daemon contracts out of Browser Node v1; the desktop host persists layout
+  through the existing Workbench snapshot
+
+### `packages/configs/*`
+
+Config packages exist to keep engineering defaults centralized and reusable.
+
+They should stay small and boring.
+
+### `packages/ui/*`
+
+UI packages define shared frontend foundations.
+
+Current packages:
+
+- `packages/ui/system`: shared tokens, icons, styles, and primitives for renderer consumers; also the repository-owned host package for shared shadcn CLI and Radix primitive acquisition
+- `packages/ui/i18n-runtime`: host-agnostic i18n runtime helpers for shared frontend packages and app-level runtime composition
+- `packages/ui/react-hooks`: host-agnostic React hook helpers for shared frontend packages, including external-store snapshot and selector patterns
+
+Rules:
+
+- keep scope limited to frontend foundation concerns such as visual-system primitives, token-backed styles, host-agnostic i18n runtime composition, and host-agnostic React subscription helpers
+- allow `ui/*` to own host-agnostic React hook foundations when the hook pattern is shared across packages and stays free of product workflows
+- prefer routing shared `useSyncExternalStore` wiring through `packages/ui/react-hooks` instead of rebuilding new subscription wrappers in feature packages
+- do not move business components, product workflows, or domain orchestration into `ui/*`
+- prefer consuming `ui/*` from app renderers and reusable frontend packages rather than recreating the same foundations locally
+- prefer narrow, stable package entrypoints over exporting internal file layout as public API
+
+### `packages/workbench/*`
+
+Workbench packages define the shared workbench boundary for the open-source
+desktop and TSH.
+
+Current packages:
+
+- `packages/workbench/snapshot`: canonical TypeScript workbench snapshot types,
+  migrations, normalization, validation, and JSON Schema. The daemon OpenAPI
+  `WorkbenchSnapshot*` component schemas are synchronized from this package.
+- `packages/workbench/service`: shared Go Workbench snapshot service, validation,
+  canonicalization, and persistence seam for daemon hosts.
+- `packages/workbench/electron`: Electron main-process Dock preview capture and
+  bounded filesystem cache mechanics. Desktop hosts still own IPC
+  authorization, BrowserWindow ownership, cache paths, and logging.
+- `packages/workbench/surface`: reusable workbench controller, reducer,
+  placement, stacking, `WorkbenchHost`, React surface primitives, shell snapshot
+  wiring, intent resolution, external-state render plumbing, and host/session
+  lifecycle mechanics for projected presence, launch requests, transient
+  activation, explicit close policy, and shell snapshot sanitation.
+
+Rules:
+
+- keep snapshot compatibility behavior in `snapshot`, not in app renderers
+- keep shared Go Workbench validation, canonicalization, and storage seams in
+  `service`, not in host daemons
+- keep shared Electron Dock preview capture and bounded cache mechanics in
+  `electron`; keep host window authorization and product diagnostics in the
+  consuming desktop app
+- keep reusable workbench interaction mechanics in `surface`, not in
+  product-specific feature UI
+- when `surface` exposes derived external-store snapshots through
+  `getSnapshot()`, unchanged source snapshots must preserve reference identity;
+  prefer the package-local derived-snapshot helper instead of rebuilding fresh
+  objects or arrays on every read
+- keep product-specific node bodies, routing, and persistence adapters in the
+  owning app or service
+- allow `surface` to own narrow default copy for generic workbench interaction
+  mechanics such as window chrome labels; keep product-specific workbench copy
+  in the owning app
+- do not widen `workbench/*` into a generic desktop shell package
+- keep package root exports intentionally small; root exports are the public
+  interface, not an index of every internal module
+- do not export test fixtures, demo data, stack internals, reducer internals, or
+  low-level hooks from a package root unless an existing consumer needs that as a
+  stable interface
+- keep adapter-specific durable state behind generic contract fields such as
+  `Record<string, unknown>` unless the adapter detail is itself part of the
+  shared snapshot contract
+
+Host reuse model:
+
+1. Keep generic workbench interaction mechanics, structural styles, and narrow
+   default copy in `packages/workbench/*`.
+2. Keep host-specific node bodies, routing, persistence adapters, and
+   product-owned workbench copy in the consuming app or service.
+3. Let the consuming host create one app-level i18n runtime that merges:
+   - host-owned i18n resources
+   - reusable package default i18n resources
+4. Scope that runtime into package namespaces such as workbench window chrome
+   instead of reconstructing per-package message objects by hand.
+
+### `packages/workspace/*`
+
+Workspace packages define reusable workspace-domain contracts that are intended
+to support a real multi-consumer boundary or a documented external contract as
+additional hosts adopt them.
+
+Current packages:
+
+- `packages/workspace/files`: Go domain kernel for logical workspace file
+  semantics, path normalization, search scoring, and host-owned file adapters.
+- `packages/workspace/file-manager`: TypeScript state, actions, adapter
+  contract, and optional React UI for a workspace file manager. Ownership
+  boundaries live in that package’s `CONTRACT.md`.
+- `packages/workspace/terminal`: shared terminal node contract and frontend
+  surface for workbench hosts.
+- `packages/workspace/issue-manager`: reusable issue-manager contracts, OpenAPI
+  fragment, i18n defaults, React surface, and workbench registration helpers
+  for workspace-scoped issue, task, and run workflows.
+
+Release rule:
+
+- npm package release participation is defined in the npm release conventions,
+  not by repeating package rosters in architecture docs
+- shared non-npm modules follow their owning language and module conventions
+  unless a separate release contract is introduced
+
+Rules:
+
+- keep host-specific adapters in the owning host, such as `services/tuttid` or
+  an app renderer feature
+- a reusable frontend workspace package may still own shared session state,
+  interaction flow, and optional React UI when those behaviors form the shared
+  workspace-domain surface rather than a product-specific host integration
+- a reusable frontend workspace package may also own narrow default copy for its
+  shared UI surface; hosts should override through their app-level i18n runtime
+  rather than duplicating package strings locally
+- keep shared state and UI on logical workspace paths such as `/workspace`, not
+  host absolute paths or VM mount paths
+- do not move tuttid storage lookup, desktop preload calls, TSH room mapping, or
+  TACH-specific integration into `packages/workspace/*`
+
+Host reuse model:
+
+1. Reuse the shared package for session orchestration, view-model derivation,
+   interaction flow, and optional UI when those behaviors are truly host-neutral.
+2. Implement host-specific transport and capability adapters in the consuming
+   host, for example preload calls, daemon clients, room bridges, or local file
+   selection surfaces.
+3. Keep shared workspace UI copy defaults in the owning package and merge them
+   through the host's app-level i18n runtime instead of copying those strings
+   into the host.
+4. Keep product-specific wording, shell integration, and user-facing host
+   behaviors in the consuming host.
+
+## Adding New Directories
+
+### Add a new top-level directory only when
+
+- the new area has a distinct deployment or ownership boundary
+- it cannot be described as part of an existing `apps/`, `services/`, `packages/`, `tools/`, or `docs/` area
+
+### Add a new app directory when
+
+- there is a new user-facing entrypoint with its own runtime shell
+
+Examples:
+
+- a desktop app
+- a CLI app
+
+Keep future app ideas in docs until they become real modules. Do not reserve them as empty directories.
+
+### Add a new service directory when
+
+- there is a new backend process with its own lifecycle and state ownership
+
+### Add a new package when
+
+- there is a real multi-consumer boundary
+- the extracted API can be named narrowly by responsibility
+- the shared code is not just convenience reuse
+- the public entrypoint can stay much smaller than the implementation tree
+
+Keep code local by default:
+
+- desktop-only TypeScript stays in `apps/desktop`
+- daemon-only Go stays in `services/tuttid`
+
+Keep future packages in docs, not in placeholder directories:
+
+- a README-only package is usually a shallow module
+- a package name should appear in the tree only when contributors can follow it to a real interface and implementation
+
+## Structure Review Questions
+
+When reviewing a new directory or package, ask:
+
+1. Which existing top-level area already owns this responsibility?
+2. Is this a real boundary or just an attempt to spread code out?
+3. Would keeping this code local be simpler and clearer?
+4. Is the new name based on responsibility instead of a vague shared label?
+5. Does the new structure reduce confusion, or just increase file count?
+6. Can a caller use the module through a small interface, or does the package
+   root expose the implementation layout?