项目文件夹

文件
wehub-resource-sync 070959e133
landing-page-staging / Deploy landing page to staging (push) Has been skipped
landing-page-ci / Validate landing page (push) Failing after 4s
visual-baseline / Capture visual baselines (push) Has been cancelled
bake-plugin-previews / Bake plugin previews (push) Has been cancelled
chore: import upstream snapshot with attribution
2026-07-13 12:00:47 +08:00

449 行
24 KiB
Markdown

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# Architecture
**Parent:** [`spec.md`](spec.md) · **Siblings:** [`skills-protocol.md`](skills-protocol.md) · [`agent-adapters.md`](agent-adapters.md) · [`modes.md`](modes.md)
This doc describes the system topology, runtime modes, data flow, and file layout. Design rationale lives in [`spec.md`](spec.md); protocol details for skills and agent adapters live in their own docs. For embedding OD behind another control plane, see [`orchestrator-workspaces.md`](orchestrator-workspaces.md).
[ocod]: https://github.com/OpenCoworkAI/open-codesign
[acd]: https://github.com/VoltAgent/awesome-claude-design
[piai]: https://github.com/badlogic/pi-mono/tree/main/packages/ai
[guizang]: https://github.com/op7418/guizang-ppt-skill
---
## 1. Three deployment topologies
OD is a web app plus a local daemon. The split means the same UI can run in three shapes:
### Topology A — Fully local (the default)
```
┌────────────────── user's machine ──────────────────┐
│ │
│ browser ──► Next.js dev server (localhost:3000) │
│ │ │
│ │ http://localhost:7456 │
│ ▼ │
│ od daemon (Node, long-running) │
│ │ │
│ ▼ │
│ spawns: claude / codex / cursor / … │
└────────────────────────────────────────────────────┘
```
One `pnpm tools-dev run web` starts both the Next.js app and the daemon. `pnpm tools-dev` adds the desktop shell. Zero config. No accounts.
### Topology B — Web on Vercel + daemon on user's machine
```
browser ──► od.yourdomain.com (Vercel)
│ ws(s):// user-provided URL (e.g. cloudflared tunnel)
od daemon on user's laptop
spawns: claude / codex / …
```
The user runs `od daemon --expose` which prints a tunnel URL; they paste the URL into the deployed web app's "Connect daemon" screen. Daemon holds secrets; Vercel holds nothing sensitive.
### Topology C — Web on Vercel + direct API (no daemon)
```
browser ──► od.yourdomain.com (Vercel serverless)
Anthropic Messages API (BYOK stored in browser)
```
No local CLI, no daemon. Degraded experience — no Claude Code skills, no filesystem artifacts (stored in IndexedDB), no PPTX export. But it's the "just try it" path. Keys stored `localStorage` with explicit warning.
The three topologies share the same web bundle; the difference is which transports are enabled.
## 2. Component diagram (logical)
```
┌─────────────────────────────── Web App ─────────────────────────────┐
│ │
│ ┌──────────┐ ┌─────────────┐ ┌───────────┐ ┌────────────────┐ │
│ │ chat pane│ │ artifact │ │ preview │ │ comment / │ │
│ │ │ │ tree │ │ iframe │ │ slider overlay │ │
│ └────┬─────┘ └──────┬──────┘ └─────┬─────┘ └────────┬───────┘ │
│ │ │ │ │ │
│ └─────────── session bus (in-memory) ──────────────┘ │
│ │ │
│ ▼ │
│ Transport layer (daemon SSE | api-direct | browser) │
└─────────────────────────┬───────────────────────────────────────────┘
┌───────────────────────┴────────────────────────────────┐
│ │
▼ (topology A/B) ▼ (topology C)
┌─────────────────────── Daemon ───────────────────────┐ ┌────────────┐
│ │ │ browser- │
│ session manager skill registry │ │ only │
│ agent adapter pool design-system resolver │ │ runtime │
│ artifact store preview compile pipeline │ │ (limited) │
│ export pipeline detection service │ └────────────┘
│ │
└─┬────────────────────────────────────────────────┬───┘
│ │
▼ ▼
┌─ agent CLIs ─┐ ┌─ filesystem ─┐
│ claude │ │ daemon data │
│ codex │ │ root │
│ cursor-agent │ │ skills/ │
│ gemini │ │ DESIGN.md │
│ opencode │ └──────────────┘
│ qwen │
└──────────────┘
```
## 3. Key components
### 3.1 Web app (Next.js 16, App Router)
- **Why Next.js, not Vite SPA?** We want SSR for the marketing landing page + serverless routes for Topology C's direct-API path + Vercel deployment as a first-class citizen. An SPA would need a separate server for any of that.
- **State:** React/browser state for UI config, with projects/conversations/files hydrated from the daemon APIs.
- **Iframe preview:** Vendored React 18 + Babel standalone for JSX artifacts, following [Open CoDesign][ocod]'s approach. HTML artifacts load raw. See [§5](#5-preview-renderer).
- **Comment mode:** Click captures `[data-od-id]` on preview DOM, opens a popover, sends `{artifact_id, element_id, note}` to daemon → agent gets a surgical edit instruction.
- **Slider UI:** When an agent emits a "tweak parameter" tool call (see [`skills-protocol.md`](skills-protocol.md) §4.2), the web app renders a live-update control that re-sends parameterized prompts without round-tripping the chat.
### 3.2 Local daemon (`od daemon`)
Single binary via `pkg` or a thin Node script distributed over npm. Responsibilities:
- Listen on `http://localhost:7456` by default. Accept REST/SSE routes under `/api/*`.
- Maintain a **session** per web tab. Sessions hold: active agent, active skill, active artifact, in-flight tool calls, design-system reference.
- Operate the **agent adapter pool**: one detected CLI = one adapter instance, reused across sessions.
- Scan and index **skills** from `~/.claude/skills/`, `./skills/`, `./.claude/skills/` on startup and on FS-watch events.
- Own the **artifact store** — writes files to disk, never in memory.
- Run the **preview compile pipeline** (Babel transform for JSX, CSS inliner for HTML exports).
- Provide export hooks for HTML/PDF/ZIP and skill-defined deck outputs.
### 3.3 Agent adapter pool
See [`agent-adapters.md`](agent-adapters.md) for the full interface. Each adapter:
1. **Detects** its target CLI (PATH lookup + config-dir probe).
2. **Spawns** the CLI with a standardized wrapper prompt + skill context + design-system context + CWD set to the project's artifact root.
3. **Streams** stdout/stderr as structured events (JSON Lines if the CLI supports it; line-based parser otherwise).
4. **Reports capabilities** — does it support multi-turn? Surgical edits? Native skill loading? Tool use?
### 3.4 Skill registry
See [`skills-protocol.md`](skills-protocol.md). Scans three locations and merges:
| Source | Priority | Purpose |
|---|---|---|
| `./.claude/skills/` | highest | project-private skills |
| `./skills/` | medium | project-declared skills |
| `~/.claude/skills/` | lowest | user-global skills |
Conflicts resolve by priority (higher wins). Each skill parsed once; watched for changes in dev.
### 3.5 Design-system resolver
- Looks for `./DESIGN.md` first, then `./design-system/DESIGN.md`, then user-configured path.
- Parses the 9-section format (see [awesome-claude-design][acd] schema).
- Injects as a prepended system message on every agent run, plus as a `{{ design_system }}` template variable skills can reference.
- Hot-reloads on file change in dev.
### 3.6 Artifact store
Plain files on disk under daemon-managed storage. This historical architecture
draft does not define current data paths. Current path rules live only in root
`AGENTS.md`**Daemon data directory contract**; read it before changing or
documenting any storage path.
Rationale:
- **Plain files** → artifacts can be inspected and exported without a proprietary binary format.
- **`artifact.json` metadata** → OD can reconstruct the artifact tree without a DB.
- **`history.jsonl` not SQLite** → append-only, git-friendly, greppable. [Open CoDesign][ocod] uses SQLite; we deliberately don't.
- **Sessions separate from artifacts** → sessions are ephemeral UI state; artifacts are durable.
### 3.7 Export pipeline
| Format | How |
|---|---|
| HTML (self-contained) | Inline all CSS, rewrite asset URLs to data: URIs |
| PDF | `puppeteer``page.pdf()` on the rendered HTML |
| PPTX | `deck-skill` outputs a JSON intermediate (`slides.json`); `pptxgenjs` generates the `.pptx` |
| ZIP | `archiver` over `artifacts/<id>/` |
| Markdown | direct copy if artifact is `.md`, otherwise skill-defined render |
## 4. Data flow — a typical "generate prototype" turn
```
1. User types prompt in web chat.
2. Web sends { method: "session.generate", params: {
sessionId, prompt, modeHint: "prototype"
}} to daemon via WS.
3. Daemon:
a. picks active skill (prototype-skill)
b. loads design-system (DESIGN.md)
c. materializes a new artifact through daemon-managed storage
d. invokes agent adapter with:
- system: skill's SKILL.md contents + DESIGN.md
- user: original prompt
- cwd: the new artifact dir
e. streams agent events back to web as they arrive:
- "tool_call" (edit file, write file, read file)
- "text_delta"
- "thinking" (if supported)
4. Web shows:
- running tool-call feed in the side panel
- artifact tree updates as files materialize
- preview iframe loads the primary output file when agent signals "done"
- slider/comment overlay activates once preview loads
5. On completion, daemon appends:
{ ts, sessionId, artifactId, action: "generate", skill, promptHash }
to history.jsonl.
6. User comments on an element → web sends { method: "session.refine", params: {
sessionId, artifactId, elementId, note }}
7. Daemon re-invokes agent with surgical-edit instruction + the note.
Adapter translates based on capabilities:
- Claude Code → native tool loop, edits that region only
- Codex → regenerates the file with "only change element X" constraint
- API fallback → same as Codex path
```
## 5. Preview renderer
**Constraints:**
- Must isolate artifact code from the host app (no access to window, cookies, parent DOM).
- Must hot-reload as the agent streams writes.
- Must support both static HTML and JSX artifacts.
**Design:**
- Always an `<iframe sandbox="allow-scripts">` — no `allow-same-origin`.
- Static HTML: `srcdoc` load of the inlined artifact.
- JSX: inject a small bootstrap that imports vendored React 18 + Babel standalone, then dynamically evals the JSX as Babel-transformed code. (This is what [Open CoDesign][ocod] does, and it works; no reason to reinvent.)
- Agent writes trigger a debounced rebuild + iframe `srcdoc` replace. Full reload each time — React state loss is acceptable at this scope.
## 6. Config files
| File | Purpose |
|---|---|
| `./skills/<skill>/SKILL.md` | skill manifest (standard Claude Code format) |
| `./DESIGN.md` | active design system ([awesome-claude-design][acd] format) |
Daemon data paths are governed only by root `AGENTS.md` → **Daemon data
directory contract**. Do not add config-path examples here.
## 7. Protocol between web and daemon
The shipped daemon uses HTTP routes plus Server-Sent Events for streaming chat output. This keeps the browser on the same `/api/*` surface in dev and production while still allowing incremental agent output.
Representative API surface:
```
GET /api/health
GET /api/agents
GET /api/skills
GET /api/design-systems
GET /api/projects
POST /api/projects
POST /api/import/folder # see Folder import
GET /api/projects/:id/files
POST /api/projects/:id/upload
POST /api/chat -> text/event-stream
POST /api/artifacts/save
```
### Folder import
`POST /api/import/folder` creates a project rooted at an existing local
folder instead of a daemon-managed project cwd. The submitted
`baseDir` is stored on `metadata.baseDir` and OD reads / writes directly
inside it — there is no copy or shadow tree. The user owns the workspace
and is responsible for their own version control (git, time machine,
etc.), mirroring how Cursor / Claude Code / Aider behave.
Safety:
- The submitted `baseDir` is canonicalized via `realpath()` before
storage, so user-controlled symlinks cannot redirect later writes.
- Standard `resolveSafe` / `sanitizePath` checks apply on every write —
`metadata.baseDir` only changes the project root, not the bounds check.
- Imports inside daemon-owned storage are refused after symlink resolution.
Before documenting daemon storage paths, you MUST read root `AGENTS.md`
**Daemon data directory contract**.
- The file panel hides the conventional build / install dirs
(`node_modules .git dist build .next .nuxt .turbo .cache .output out
coverage __pycache__ .venv vendor target .tmp`) so the listing
stays focused on design content.
Request / response types: `ImportFolderRequest`, `ImportFolderResponse`
in `@open-design/contracts`.
#### Desktop folder-import auth (PR #974)
The desktop build adds a privileged `shell.openPath` IPC bridge so the
"Continue in CLI" / "Finalize design package" buttons can reveal a
project's working directory in Finder/Explorer. To prevent a
compromised renderer from abusing that bridge to open arbitrary local
paths via project-creation laundering, `POST /api/import/folder` is
fronted by an HMAC gate when the daemon is paired with a desktop:
- **Trust handshake.** At desktop main-process startup, before the
`BrowserWindow` is created, desktop generates a fresh 32-byte secret
(`randomBytes(32)`) and registers it with the daemon over the
daemon's sidecar IPC (`SIDECAR_MESSAGES.REGISTER_DESKTOP_AUTH`).
- **Token shape.** When the user picks a folder via the
`dialog:pick-and-import` IPC, the desktop main process mints an HMAC
token `${nonce}~${expISO}~${signatureB64url}` where
`signature = HMAC-SHA256(secret, baseDir + "\n" + nonce + "\n" + exp)`.
The token is sent in `X-OD-Desktop-Import-Token` alongside the
`POST /api/import/folder` body. Field separator is `~` (not `.`)
because ISO 8601 expiries embed `.` and would split the token into
four parts.
- **TTL & replay.** Tokens are single-use: the daemon rejects nonces
it has already consumed and prunes them on expiry. TTL is 60s;
expiries beyond 2× TTL are also rejected so a compromised desktop
cannot mint long-lived tokens against a small TTL contract.
- **Fail-closed.** Two coordinated mechanisms prevent the gate from
silently relaxing when the desktop's registration is in flight or
has been lost (daemon restart mid-session, IPC race at startup):
- A **sticky in-process flag**: once a secret has ever been
registered with this daemon process, the gate stays active for
the rest of the process lifetime (a `setDesktopAuthSecret(null)`
call from tests does not relax it).
- An **orchestrator-pinned mode** via the `OD_REQUIRE_DESKTOP_AUTH=1`
env var, set by `tools-dev` / `tools-pack` / `apps/packaged` when
the daemon is spawned in a desktop-bundled flow. With the env set,
the gate is active from request 0 — a renderer that races to call
`/api/import/folder` before the desktop has registered gets a 503
`DESKTOP_AUTH_PENDING` (transient, retry).
- **Web-only deployments are unaffected.** When neither mechanism
fires (standalone daemon spawn, no env var, no desktop ever paired),
the gate stays dormant and `/api/import/folder` behaves as before.
Browser-only builds have no `shell.openPath` surface, so a
renderer-named path cannot escalate.
- **Trusted-picker marker on `openPath`.** Every import that passes
the HMAC gate is stamped with `metadata.fromTrustedPicker: true`.
The desktop main process's `shell:open-path` IPC refuses
folder-imported projects whose metadata lacks this marker — even if
a future codepath inadvertently sets `metadata.baseDir` outside the
trusted flow, the open-path surface stays closed. `POST /api/projects`
and `PATCH /api/projects/:id` reject any client-supplied
`fromTrustedPicker` so the marker cannot be smuggled or stripped.
- **Legacy migration.** Folder-imported projects created before this
gate landed have no `fromTrustedPicker` flag. The "Continue in CLI"
button will return an error toast for those projects; the user
re-imports the same folder via the picker to restore the button.
- **Daemon restart edge.** If the daemon is restarted while desktop
keeps running, the new daemon process will be in `OD_REQUIRE_DESKTOP_AUTH`
mode (orchestrator env survives restart) but has no secret registered
yet, so the first import after the restart returns `503
DESKTOP_AUTH_PENDING`. The desktop runtime catches that response in
`dialog:pick-and-import`, re-invokes its registration callback to
re-handshake with the new daemon, mints a fresh token (new nonce + new
exp — replay protection still works), and retries once. A persistent
failure (daemon truly down, IPC socket missing) surfaces in the
renderer toast instead of silently dropping. No desktop restart needed.
- **Headless packaged mode.** The headless entrypoint
(`apps/packaged/src/headless.ts`) starts daemon + web only — no
Electron, no `shell.openPath` surface, no desktop main process to
register a secret. It calls `startPackagedSidecars(...)` with
`requireDesktopAuth: false`, which keeps the daemon's gate dormant
for that deployment. The Electron entry
(`apps/packaged/src/index.ts`) passes `true` because it does start
desktop main alongside the daemon.
- **tools-dev split-start hardening.** `tools-dev start desktop`
introspects the running daemon's STATUS over IPC before launching
desktop main. The split-start dev sequence
`tools-dev start daemon``tools-dev start desktop` would
otherwise leave the daemon running without
`OD_REQUIRE_DESKTOP_AUTH=1` (the env var is only injected when
daemon and desktop spawn in the same orchestrator invocation, or
when a desktop is already alive at daemon spawn time). When
`start desktop` finds an ungated daemon
(`desktopAuthGateActive: false` on the new STATUS field), tools-dev
stops the daemon (and web, if running), respawns the daemon with
the env var pinned, restarts web, and only then launches desktop
main. The user sees a single `[tools-dev] daemon is running
without desktop-auth gate; restarting daemon (and web, if running)
before desktop start` line; in-flight daemon work is interrupted
but the gate is guaranteed armed before the BrowserWindow loads.
The bundled-targets path (`pnpm tools-dev`) is unaffected — its
daemon was already spawned gated by the same-invocation trigger,
so the helper is a single STATUS roundtrip with no side effects.
Packaged Electron and packaged headless modes are unaffected
because their gate state is fixed at packaged-runtime startup.
Shared API contract types live in [`packages/contracts/src`](../packages/contracts/src).
## 8. Deployment
### Local
```sh
pnpm install
pnpm tools-dev run web # starts daemon + web foreground loop
```
When a reverse proxy sits in front of the daemon, `/api/*` includes SSE streams and must stay unbuffered. The daemon sends `Cache-Control: no-cache, no-transform` and `X-Accel-Buffering: no`, and also emits SSE comment keepalives, but nginx can still break chunked streams if gzip is enabled. For nginx, set `proxy_buffering off;`, `gzip off;`, and long `proxy_read_timeout` / `proxy_send_timeout` values on the API location. Otherwise browsers can report `net::ERR_INCOMPLETE_CHUNKED_ENCODING 200 (OK)` on long generations.
### Docker
```yaml
# docker-compose.yml
services:
daemon:
image: openclaudedesign/daemon
volumes: [ "./:/workspace" ]
ports: ["7456:7456"]
web:
image: openclaudedesign/web
ports: ["3000:3000"]
environment: [ "OD_DAEMON_URL=http://daemon:7456" ]
```
### Vercel + local daemon (Topology B)
```sh
vercel deploy # web only
od daemon --expose # user runs locally; prints tunnel URL
# user pastes URL into /connect UI
```
### Vercel direct (Topology C)
```sh
vercel deploy # same bundle
# flip VERCEL env flag OD_MODE=direct to hide daemon-connect UI
```
## 9. Security model
| Surface | Threat | Mitigation |
|---|---|---|
| Daemon HTTP/SSE API | Arbitrary local process talks to daemon | Bind to localhost by default; add auth/tunnel hardening before exposing beyond the machine |
| Artifact code in preview | XSS/cookie theft from host | `<iframe sandbox="allow-scripts">`, no `allow-same-origin` |
| Agent running on user's machine | Agent reads/writes outside project | Adapter sets `cwd` to artifact dir; relies on agent's own permission system (Claude Code's `--allowed-tools` etc.) |
| User secrets | Leak to cloud | BYOK stored only in daemon's `config.toml` (mode 0600) or browser `localStorage` in Topology C, never sent to OD's own servers (we don't have any) |
| Skill from untrusted source | Malicious skill in `~/.claude/skills/` | Install-time warning; skills run under the agent's permission model, not ours |
| Vercel web bundle | Compromised build | Standard Vercel integrity; bundle has zero secrets |
We inherit the agent's permission model on purpose — we don't invent our own sandbox, because Claude Code's `--permission-mode` / Codex's sandboxing / Cursor's containment already exist and are maintained.
## 10. Performance notes
- Daemon startup: < 500 ms (lazy adapter init).
- Agent detection: < 200 ms (parallel PATH probes).
- First generation latency: dominated by agent model time; OD overhead should be < 50 ms.
- Preview reload: debounced 100 ms on artifact file writes.
- Skill index: cold scan < 100 ms for ~50 skills; watched with `chokidar`.
## 11. What's explicitly out of scope for MVP
- Multi-user / RBAC / orgs
- Hosted skill marketplace (git URLs only in v1)
- Figma export (post-1.0, same as [Open CoDesign][ocod])
- Collaborative editing
- Mobile web support (desktop only in MVP)
- Offline mode (beyond "the agent is local" — we don't cache model responses)