docs: record remote main integration

This commit is contained in:
2026-08-31 14:56:40 +08:00
parent 372b5345da
commit 93fba75f74
5 changed files with 128 additions and 5 deletions

View File

@@ -7,6 +7,7 @@
| `electron/coding-plugins/manifest.ts`, `release-descriptor.ts`, `signature-verifier.ts`, and `trusted-keys.ts` | Closed Plugin package/descriptor parsing, compatibility checks, canonical archive validation, and Ed25519 trust | Schema 1 bundled compatibility and schema 2 `skill_only`/declarative `platform_hosted` are parsed fail closed. The production trust store accepts no Marketplace package until the official public key is built in. |
| `electron/coding-plugins/account-plugin-cache.ts`, `marketplace-client.ts`, and `package-store.ts` | Main-owned Account Library cache, authenticated server client, and atomic immutable device installation store | Account acquisition and device installation are separate. Package bytes switch atomically only after descriptor, signature, archive, client-range, and provenance checks; failed updates preserve the prior current release. |
| `electron/coding-plugins/effective-resolver.ts`, `registry.ts`, `project-service.ts`, and `electron/coding-runtime/pi/**` | One effective installed-plugin projection and frozen parent logical-thread runtime snapshot | Project enablement and Agent Skill assignment are preserved independently. Only trusted, compatible, installed, policy-admitted resources enter a new parent logical thread; child workers remain empty and active threads retain frozen bytes until disposal. |
| `electron/coding-plugins/adapters/game-resource.ts` and `electron/services/game-resource-client.ts` | Provider-neutral `makelore.game-resource` hosted tool adapter and Main-owned Works Square transport | Tools materialize only from an eligible frozen `platform_hosted` parent snapshot. Metered mutations require explicit confirmation and stable logical operation identity; Renderer/Pi never receive Provider URLs, credentials, balances, raw responses, or Provider job IDs. |
| `electron/api/routes/plugin-marketplace.ts`, `src/stores/plugin-marketplace.ts`, `src/pages/PluginMarketplace/`, `src/pages/MyPlugins/`, and `src/pages/ProjectPlugins/` | Bounded Main routes and Renderer projections for catalog, Library, device, and project actions | Renderer receives no Account token, filesystem path, Admission, package bytes, or signed download URL. Catalog/Library/device/project generations prevent stale A/B or cross-action results from replacing current state. |
| `src/components/works/ProjectPublishAction.tsx` | 可发布项目的一键提交、云构建轮询与用户可理解状态 | 只通过 Renderer API 提交非敏感元数据;绑定告警不终止轮询 |
| `src/lib/works-square.ts` | Renderer 侧 Works Square Host API 契约与安全错误映射 | 不接触 Token、ZIP、本地绝对路径或自动部署状态 |
@@ -53,6 +54,7 @@
## Dependency Direction
- Renderer UI → Renderer API contract → Main Host routes → Main services → Works Square;Renderer 不反向读取 Main 凭据、文件系统或归档。
- Hosted Plugin parent tool → frozen Registry adapter → Main `GameResourceClient` → fixed Works Square game-resource routes. Stable logical operation identity survives response loss and Main restart; ambiguous submission remains reviewable and is never converted into an automatic fresh mutation. Saving a result uses the existing bounded project path and project write lease.
- AI 编程 Renderer product Snapshot/commands → typed `/api/coding/*` Host API → Main Coding composition → target `CodingConversationRuntime` → shared Agent Server 内的目标 Pi 逻辑线程;Pi Provider 请求再经 Main AI proxy 访问模型上游。Renderer 不持有 Pi wire、凭据或本地 runtime URL。
- Project configuration 决定产品分流;Main release builder 生成 source/built/contract,服务端独立重算和校验决定发布安全,本地 `ProjectType` 不是授权结论。
- Built artifact preflight 检查最终上传的同字节快照,但客户端可被绕过且不产生可信 receipt;服务端仍是合同、摘要和不可变 Release 安全权威。
@@ -63,6 +65,7 @@
## Risky Or Sensitive Areas
- `electron/api/routes/works.ts` 同时承担发布 capability、上游安全投影和错误脱敏,变更时必须验证未在拒绝前读取凭据或项目文件。
- `platform_hosted` mutation eligibility, explicit confirmation, stable identity, Admission and receipt status form one authority chain. `submission_unknown` cannot create a new request, and a billing `pending_review` receipt cannot be inferred from transport ambiguity. Production remains fail closed until the official Marketplace signing key and server-side activation gates are ready.
- `project-release-builder.ts` 执行受信本地项目的 Vite config/plugins,拥有桌面用户权限;必须保持路径、环境、时间、输出、进程树和临时目录限制,不得包装为 sandbox。
- `electron/agent-browser/module.ts` 的预检必须继续拒绝外域访问、隔离临时 partition 并清理所有 view/listener;不能因本地通过而跳过服务端逐字节校验。生产 opaque-origin 行为不由该 loopback 检查覆盖。
- `works-cloud-deploy.json` 是兼容文件名;不得因名称重新引入自动部署协调语义。