完成 Editor Agent Mock Agent P1 收尾

接入 Web Project 契约、SpacetimeDB 表与 api-server 控制面
新增 Mock Agent、静态构建 runner 与独立预览网关
补齐 /editor/agent 前端页面、服务客户端和 SSE 订阅
修复 sandbox 预览资源跨域加载并补充并发保护
接入本地 dev 预览端口漂移与服务身份初始化
更新 P1 技术方案、验收清单和 Hermes 共享记忆

packages/shared/src/contracts/webProject.ts

@@ -0,0 +1,110 @@
+export const WEB_PROJECT_TEMPLATE_REACT_VITE_TS_STATIC =
+  'react-vite-ts-static' as const;
+
+export type WebProjectPreviewBuildStatus =
+  | 'queued'
+  | 'running'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'expired'
+  | 'stale';
+
+export interface WebProject {
+  projectId: string;
+  ownerUserId: string;
+  title: string;
+  templateKey: typeof WEB_PROJECT_TEMPLATE_REACT_VITE_TS_STATIC;
+  activeSnapshotId: string;
+  activePreviewBuildId?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WebProjectFile {
+  /** P1 只接受相对路径，拒绝路径穿越、敏感文件和固定模板控制文件。 */
+  path: string;
+  /** P1 只保存 UTF-8 文本源码或受控静态文本资源，大小由后端统一限制。 */
+  content: string;
+  mediaType: string;
+  encoding: 'utf-8';
+  /** 后端按 UTF-8 字节数计算，参与 snapshot 总大小限制。 */
+  sizeBytes: number;
+}
+
+export interface WebProjectSnapshot {
+  snapshotId: string;
+  projectId: string;
+  ownerUserId: string;
+  parentSnapshotId?: string | null;
+  templateKey: typeof WEB_PROJECT_TEMPLATE_REACT_VITE_TS_STATIC;
+  files: WebProjectFile[];
+  patchSummary: string;
+  createdBy: string;
+  createdAt: string;
+}
+
+export type WebProjectPatchOperation =
+  /** 仅允许创建 P1 可编辑范围内的文件，不能创建依赖、脚本或模板控制文件。 */
+  | { type: 'createFile'; path: string; content: string }
+  /** 仅允许更新 P1 可编辑范围内的文件。 */
+  | { type: 'updateFile'; path: string; content: string }
+  /** 删除同样受路径白名单约束，避免绕过固定模板边界。 */
+  | { type: 'deleteFile'; path: string }
+  /** 源路径和目标路径都必须通过 P1 可编辑路径校验。 */
+  | { type: 'renameFile'; fromPath: string; toPath: string }
+  /** package.json 不是依赖事实源；P1 拒绝 scripts / dependencies 等供应链字段。 */
+  | { type: 'packageManifestRequest'; content: string };
+
+export interface WebProjectPatch {
+  /** 所有 patch 操作必须先经过后端统一校验，再生成新 snapshot。 */
+  operations: WebProjectPatchOperation[];
+}
+
+export interface WebProjectPreviewBuild {
+  jobId: string;
+  projectId: string;
+  snapshotId: string;
+  ownerUserId: string;
+  status: WebProjectPreviewBuildStatus;
+  logs: string[];
+  artifactId?: string | null;
+  /** 后端保存的不透明预览票据；前端只消费 previewUrl，不拼接或解析 token。 */
+  previewTokenId?: string | null;
+  previewUrl?: string | null;
+  errorSummary?: string | null;
+  createdAt: string;
+  startedAt?: string | null;
+  finishedAt?: string | null;
+  updatedAt: string;
+}
+
+export interface WebProjectPreviewBuildEvent {
+  jobId: string;
+  status: WebProjectPreviewBuildStatus;
+  message?: string | null;
+  build?: WebProjectPreviewBuild | null;
+}
+
+export interface MockAgentTurnRequest {
+  prompt: string;
+  baseSnapshotId: string;
+}
+
+export interface MockAgentTurnResponse {
+  snapshot: WebProjectSnapshot;
+  patch: WebProjectPatch;
+  summary: string;
+}
+
+export interface WebProjectResponse {
+  project: WebProject;
+}
+
+export interface WebProjectSnapshotResponse {
+  snapshot: WebProjectSnapshot;
+}
+
+export interface WebProjectPreviewBuildResponse {
+  build: WebProjectPreviewBuild;
+}

packages/shared/src/index.ts

@@ -51,6 +51,7 @@ export type {
 } from './contracts/squareHoleWorks';
 export type * from './contracts/story';
 export type * from './contracts/visualNovel';
+export type * from './contracts/webProject';
 export * from './http';
 export * from './llm/narrativeLanguage';
 export * from './llm/parsers';