@xpert-ai/plugin-spaces 0.0.0-stage → 0.3.0

package/dist/subpages.js

@@ -0,0 +1,118 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { ConflictException, Injectable } from '@nestjs/common';
+import { z } from 'zod/v3';
+import { SpaceAccess } from './access.js';
+import { Space } from './entities.js';
+import { SpaceDocuments, contentHash, safeName } from './documents.js';
+import { SpaceArtifacts } from './artifacts.js';
+import { denied, scoped } from './domain.js';
+const create = z.object({ requestId: z.string().uuid(), title: z.string().trim().min(1).max(180) });
+const missing = (error) => error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+const entry = (item) => ({ resourceId: item.id, title: item.title, path: item.filePath });
+/** Logical hierarchy is metadata, never an ACL or a disguised file folder.
+ * Each create owns one stable resource/path. Retry resumes publication instead of duplicating a child.
+ * Parent rename/move/trash does not mutate independent child files; a restored parent reconnects them.
+ */
+let SpaceSubpages = class SpaceSubpages {
+    access;
+    documents;
+    artifacts;
+    constructor(access, documents, artifacts) {
+        this.access = access;
+        this.documents = documents;
+        this.artifacts = artifacts;
+    }
+    actor(input) { return { ...input.actor, projectId: input.projectId, assistantId: input.assistantId }; }
+    async parent(input, write = false) {
+        const result = await this.access.resource(this.actor(input), input.sourceResourceId, write ? 'write' : 'read');
+        if (!result.item || result.item.kind !== 'page' || !result.item.filePath || result.space.projectId !== input.projectId)
+            throw denied();
+        return { ...result, item: result.item };
+    }
+    async hierarchy(input) {
+        const { item, space, canWrite } = await this.parent(input);
+        const actor = this.actor(input);
+        const visible = async (candidate) => {
+            if (!candidate || candidate.deleted || candidate.editorKey !== 'markdown.tiptap' || !candidate.filePath)
+                return null;
+            try {
+                await this.access.resource(actor, candidate.id, 'read');
+                return entry(candidate);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'spaces.access_denied')
+                    return null;
+                throw error;
+            }
+        };
+        const parent = item.parentPageId ? await visible(await this.access.items.findOneBy({ ...scoped(actor), spaceId: space.id, id: item.parentPageId })) : null;
+        const rows = await this.access.items.find({ where: { ...scoped(actor), spaceId: space.id, parentPageId: item.id, deleted: false },
+            order: { createdAt: 'ASC' }, take: 101 });
+        const children = (await Promise.all(rows.slice(0, 100).map(visible))).filter((value) => value !== null);
+        return { supported: true, canCreate: canWrite, parent, children, hasMore: rows.length > 100 };
+    }
+    async createChild(input) {
+        const request = create.parse(input), actor = this.actor(input);
+        const { space } = await this.parent(input, true);
+        // Use the same Space lock as folder moves/discovery. Only the lock uses this transaction;
+        // publication is a retryable saga and its intent must survive process failure.
+        return this.access.items.manager.transaction(async (manager) => {
+            await manager.getRepository(Space).findOneOrFail({ where: { ...scoped(actor), id: space.id }, lock: { mode: 'pessimistic_write' } });
+            const { item: parent } = await this.parent(input, true);
+            let item = await this.access.items.findOneBy({ id: request.requestId });
+            if (item && (item.tenantId !== actor.tenantId || item.organizationId !== actor.organizationId || item.spaceId !== space.id ||
+                item.parentPageId !== parent.id || item.childRequestTitle !== request.title || item.createdById !== actor.userId || item.deleted))
+                throw new ConflictException('spaces.child_request_conflict');
+            if (!item) {
+                // New IDs cannot make cycles. Bound depth so corrupt metadata cannot loop forever.
+                // Count the child itself as level one, then count its ancestors.
+                let cursor = parent, depth = 1;
+                while (cursor) {
+                    if (++depth > 32 || cursor.id === request.requestId)
+                        throw new ConflictException('spaces.page_depth');
+                    cursor = cursor.parentPageId ? await this.access.items.findOneBy({ ...scoped(actor), spaceId: space.id, id: cursor.parentPageId }) : null;
+                }
+                const directory = parent.filePath.slice(0, parent.filePath.lastIndexOf('/') + 1);
+                // Resource suffix avoids collisions between equally named children and unrelated files.
+                const filePath = `${directory}${safeName(request.title).slice(0, 100)}--${request.requestId}.md`;
+                item = await this.access.items.save(this.access.items.create({ ...scoped(actor), id: request.requestId,
+                    spaceId: space.id, parentId: parent.parentId, parentPageId: parent.id, childRequestTitle: request.title,
+                    createdById: actor.userId, kind: 'page', title: request.title, filePath, syncStatus: 'pending' }));
+            }
+            if (item.editorKey === 'markdown.tiptap')
+                return { documentId: item.id };
+            const fileScope = { actor, projectId: input.projectId, path: item.filePath };
+            const markdown = `# ${request.title.replace(/[\\`*_{}\[\]()#+.!<>|$]/gu, '\\$&')}\n\n`;
+            const buffer = Buffer.from(markdown), hash = contentHash(buffer);
+            const disk = await this.documents.api().read(fileScope).catch((error) => { if (missing(error))
+                return null; throw error; });
+            if (disk && disk.sha256 !== (item.fileHash ?? hash))
+                throw new ConflictException('spaces.file_conflict');
+            if (!disk) {
+                if (item.fileHash)
+                    throw new ConflictException('spaces.file_conflict');
+                await this.documents.api().write({ ...fileScope, buffer, expectedHash: null });
+            }
+            await this.access.items.update(item.id, { fileHash: disk?.sha256 ?? hash, syncStatus: 'ready' });
+            await this.documents.content().register({ actor, assistantId: input.assistantId, projectId: input.projectId,
+                resourceId: item.id, path: item.filePath, title: item.title, modelKey: 'markdown.tiptap', source: { providerKey: 'spaces', resourceId: item.id } });
+            if (!item.artifactId)
+                await this.artifacts.initializePage(actor, item.id, item.title);
+            await this.access.items.update(item.id, { editorKey: 'markdown.tiptap' });
+            return { documentId: item.id };
+        });
+    }
+};
+SpaceSubpages = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [SpaceAccess, SpaceDocuments, SpaceArtifacts])
+], SpaceSubpages);
+export { SpaceSubpages };

package/dist/view.d.ts

@@ -0,0 +1,99 @@
+import { SpaceCatalog } from './catalog.js';
+import { SpaceImports } from './imports.js';
+import type { XpertExtensionViewManifest, XpertResolvedViewHostContext, XpertViewQuery, XpertViewActionRequest, XpertRemoteComponentViewSchema, XpertViewFileAccessRequest } from '@xpert-ai/contracts';
+import { type IXpertViewExtensionProvider, type XpertViewFileActionFile } from '@xpert-ai/plugin-sdk';
+import { SpacesService } from './spaces.js';
+import { SpacePages } from './pages.js';
+import { SpaceAi } from './ai.js';
+import { SpaceEditors } from './editors.js';
+import { SpaceFiles } from './files.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpaceContent } from './content.js';
+import { SpaceAccess } from './access.js';
+export declare class SpacesView implements IXpertViewExtensionProvider {
+    private readonly catalog;
+    private readonly imports;
+    private readonly content;
+    private readonly spaces;
+    private readonly pages;
+    private readonly ai;
+    private readonly files;
+    private readonly editors;
+    private readonly knowledge;
+    private readonly access;
+    constructor(catalog: SpaceCatalog, imports: SpaceImports, content: SpaceContent, spaces: SpacesService, pages: SpacePages, ai: SpaceAi, files: SpaceFiles, editors: SpaceEditors, knowledge: SpaceKnowledge, access: SpaceAccess);
+    supports(context: XpertResolvedViewHostContext): boolean;
+    getViewManifests(context: XpertResolvedViewHostContext, slot: string): XpertExtensionViewManifest[];
+    getRemoteComponentEntry(context: XpertResolvedViewHostContext, viewKey: string, component: XpertRemoteComponentViewSchema['component']): Promise<{
+        html: string;
+        contentType: "text/html; charset=utf-8";
+    }>;
+    getViewData(context: XpertResolvedViewHostContext, viewKey: string, query: XpertViewQuery): Promise<{
+        items: never[];
+        meta: {
+            requiresProject: boolean;
+        };
+    } | {
+        items: never[];
+        meta: {
+            project: {
+                id: string;
+                title: string;
+            };
+            assistant: {
+                id: string;
+                title: string;
+                dataScope: string;
+            };
+            root: import("./entities.js").Space | import("./entities.js").SpaceItem;
+            role: "editor" | "manager" | "owner" | "member";
+            canWrite: boolean;
+            canManage: boolean;
+            items: (import("./entities.js").SpaceItem & {
+                role: string;
+            })[];
+            requiresProject?: undefined;
+        };
+    }>;
+    executeViewAction(context: XpertResolvedViewHostContext, viewKey: string, action: string, request: XpertViewActionRequest): Promise<{
+        success: boolean;
+        refresh: boolean;
+        data: object;
+    }>;
+    /** Check once per View request, before accessing resources or serving the empty state.
+     * Resource services still enforce their own Project and operation ACLs. */
+    private actor;
+    private runAction;
+    executeViewFileAction(context: XpertResolvedViewHostContext, viewKey: string, actionKey: string, request: XpertViewActionRequest, file: XpertViewFileActionFile): Promise<{
+        success: boolean;
+        data: import("./entities.js").SpaceItem;
+        refresh?: undefined;
+    } | {
+        success: boolean;
+        refresh: boolean;
+        data: {
+            item: import("./entities.js").SpaceItem;
+            version: import("./entities.js").SpaceFileVersion;
+        };
+    }>;
+    resolveViewFile(context: XpertResolvedViewHostContext, viewKey: string, request: XpertViewFileAccessRequest): Promise<{
+        reference: {
+            userId: string;
+            projectId: string;
+            catalog: "projects";
+            source: "platform.workspace.files";
+            filePath: string;
+            scopeId: string;
+            workspacePath: string;
+            tenantId: string;
+            organizationId: string;
+        };
+        fileName: string;
+        mimeType: string;
+    } | {
+        reference: import("@xpert-ai/plugin-sdk").WorkspacePortableFileReference;
+        fileName: string;
+        mimeType: string;
+        size: number | undefined;
+    }>;
+}

package/dist/view.js

@@ -0,0 +1,259 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { SpaceCatalog, catalogQuery, catalogCreate, catalogRename, catalogDuplicate, catalogLifecycle, catalogMove } from './catalog.js';
+import { SpaceImports, sourceSelection, importSelection } from './imports.js';
+import { BadRequestException, Injectable } from '@nestjs/common';
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod/v3';
+import { ViewExtensionProvider, renderRemoteReactIframeHtml } from '@xpert-ai/plugin-sdk';
+import { actorSchema, denied, id, PLUGIN, VIEW } from './domain.js';
+import { createItemSchema, editItemSchema, SpacesService } from './spaces.js';
+import { SpacePages } from './pages.js';
+import { SpaceAi } from './ai.js';
+import { SpaceEditors } from './editors.js';
+import { SpaceFiles } from './files.js';
+import { SpaceKnowledge } from './knowledge.js';
+import { SpaceContent } from './content.js';
+import { SpaceAccess } from './access.js';
+const selection = z.object({ itemId: id }).strict();
+const label = (en_US, zh_Hans) => ({ en_US, zh_Hans });
+const actions = ['catalog.duplicate', 'catalog.backup', 'catalog.preferences', 'catalog.preference.set', 'catalog.move', 'catalog.types', 'catalog.list', 'catalog.create', 'catalog.rename', 'catalog.lifecycle', 'source.list', 'source.search', 'source.preview', 'source.import', 'document.open', 'knowledge.enable',
+    'knowledge.status', 'knowledge.refresh', 'knowledge.search', 'item.create', 'item.edit', 'page.read', 'search',
+    'file.list', 'page.export', 'artifact.list', 'artifact.collect', 'artifact.open', 'editor.list', 'editor.create'];
+let SpacesView = class SpacesView {
+    catalog;
+    imports;
+    content;
+    spaces;
+    pages;
+    ai;
+    files;
+    editors;
+    knowledge;
+    access;
+    constructor(catalog, imports, content, spaces, pages, ai, files, editors, knowledge, access) {
+        this.catalog = catalog;
+        this.imports = imports;
+        this.content = content;
+        this.spaces = spaces;
+        this.pages = pages;
+        this.ai = ai;
+        this.files = files;
+        this.editors = editors;
+        this.knowledge = knowledge;
+        this.access = access;
+    }
+    supports(context) {
+        return context.hostType === 'agent' && context.capabilities?.features?.includes('spaces') === true;
+    }
+    getViewManifests(context, slot) {
+        if (!this.supports(context) || !['agent.workbench.main', 'agent.workbench.fixed'].includes(slot))
+            return [];
+        return [{ key: VIEW, title: label('Spaces', '协作空间'), hostType: context.hostType, slot,
+                source: { provider: 'spaces.views', plugin: PLUGIN }, refreshable: true,
+                activation: { requiredFeatures: ['spaces'] },
+                workbench: slot === 'agent.workbench.fixed' ? { fixed: true, menu: { enabled: true, label: label('Spaces', '协作空间'), order: 35 } } : {},
+                view: { type: 'remote_component', runtime: 'react', protocolVersion: 1,
+                    component: { isolation: 'iframe', entry: 'spaces' }, dataSource: { mode: 'platform' } },
+                dataSource: { mode: 'platform', cache: { enabled: false }, querySchema: { supportsSelection: true, supportsParameters: true } },
+                fileAccess: { purposes: ['download'] },
+                actions: [...actions.map((key) => ({ key, label: label(key, key), actionType: 'invoke' })),
+                    { key: 'editor.import', label: label('Import document', '导入文档'), actionType: 'invoke', transport: 'file' },
+                    { key: 'file.upload', label: label('Upload file', '上传文件'), actionType: 'invoke', transport: 'file' }],
+                // Declare both phases: platform resource resolution, then container-local navigation.
+                clientCommands: ['assistant.chat.send_message', 'assistant.context.set', 'workbench.content.resolve', 'workbench.navigation.open'].map((key) => ({ key, required: key === 'workbench.content.resolve', label: label(key, key) })) }];
+    }
+    async getRemoteComponentEntry(context, viewKey, component) {
+        if (viewKey !== VIEW || component.entry !== 'spaces')
+            throw new Error('spaces.view_missing');
+        const actor = await this.actor(context, false);
+        if (actor.projectId)
+            await this.spaces.workspace(actor);
+        const [appScript, appCss] = await Promise.all(['app.js', 'app.css'].map((name) => readFile(new URL(`./remote/${name}`, import.meta.url), 'utf8')));
+        return { html: renderRemoteReactIframeHtml({ title: 'Spaces', reactUmd: '', reactDomUmd: '', appScript, appCss }), contentType: 'text/html; charset=utf-8' };
+    }
+    async getViewData(context, viewKey, query) {
+        if (viewKey !== VIEW)
+            throw new Error('spaces.view_missing');
+        const actor = await this.actor(context, false);
+        if (!actor.projectId)
+            return { items: [], meta: { requiresProject: true } };
+        const space = await this.spaces.workspace(actor);
+        const resourceId = !query.selectionId || query.selectionId === 'root' ? space.id : id.parse(query.selectionId);
+        return { items: [], meta: { ...await this.spaces.tree(actor, resourceId, query.parameters?.trash === true),
+                project: { id: space.projectId, title: space.title },
+                assistant: { id: context.hostId, title: space.title, dataScope: 'project' } } };
+    }
+    async executeViewAction(context, viewKey, action, request) {
+        try {
+            return await this.runAction(context, viewKey, action, request);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError)
+                throw new BadRequestException('spaces.invalid_input');
+            throw error;
+        }
+    }
+    /** Check once per View request, before accessing resources or serving the empty state.
+     * Resource services still enforce their own Project and operation ACLs. */
+    async actor(context, requireProject = true) {
+        if (!this.supports(context))
+            throw denied();
+        const actor = actorSchema.extend({ assistantId: id }).parse({ ...context, assistantId: context.hostId, projectId: context.runtimeScope?.projectId ?? undefined });
+        if (requireProject && !actor.projectId)
+            throw denied();
+        await this.access.assistant(actor);
+        return actor;
+    }
+    async runAction(context, viewKey, action, request) {
+        if (viewKey !== VIEW)
+            throw new Error('spaces.view_missing');
+        if (!actions.includes(action))
+            throw new Error('spaces.action_unknown');
+        const actor = await this.actor(context), input = request.input;
+        await this.spaces.workspace(actor);
+        let result;
+        switch (action) {
+            case 'source.list':
+                result = await this.imports.sources(actor);
+                break;
+            case 'source.search':
+                result = await this.imports.search(actor, z.object({ bindingId: id, query: z.string().trim().max(200).default(''), cursor: z.string().max(2000).optional(), pageSize: z.number().int().min(1).max(50).default(25) }).strict().parse(input));
+                break;
+            case 'source.preview':
+                result = await this.imports.preview(actor, sourceSelection.parse(input));
+                break;
+            case 'source.import':
+                result = await this.imports.apply(actor, importSelection.parse(input));
+                break;
+            case 'document.open':
+                result = await this.content.open(actor, selection.parse(input).itemId);
+                break;
+            case 'knowledge.enable':
+            case 'knowledge.status':
+            case 'knowledge.refresh': {
+                const p = z.object({ spaceId: id }).strict().parse(input);
+                result = action === 'knowledge.enable' ? await this.knowledge.enable(actor, p.spaceId)
+                    : action === 'knowledge.refresh' ? await this.knowledge.refresh(actor, p.spaceId) : await this.knowledge.status(actor, p.spaceId);
+                break;
+            }
+            case 'knowledge.search': {
+                const p = z.object({ spaceId: id, query: z.string().trim().min(1).max(4000) }).strict().parse(input);
+                result = await this.knowledge.search(actor, p.spaceId, p.query);
+                break;
+            }
+            case 'catalog.backup':
+                result = await this.catalog.backup(actor, z.object({ contentId: id }).strict().parse(input).contentId);
+                break;
+            case 'catalog.preferences':
+                result = await this.catalog.preferences(actor, z.object({ contentId: id }).strict().parse(input).contentId);
+                break;
+            case 'catalog.preference.set':
+                result = await this.catalog.setPreference(actor, z.object({ contentId: id, scope: z.enum(['resource', 'project', 'organization']), editorKey: z.string().min(1).max(200).nullable(), expectedRevision: z.number().int().nonnegative() }).strict().parse(input));
+                break;
+            case 'catalog.move':
+                result = await this.catalog.move(actor, catalogMove.parse(input));
+                break;
+            case 'catalog.types':
+                result = await this.catalog.types(actor);
+                break;
+            case 'catalog.list':
+                result = await this.catalog.list(actor, catalogQuery.parse(input));
+                break;
+            case 'catalog.lifecycle':
+                result = await this.catalog.lifecycle(actor, catalogLifecycle.parse(input));
+                break;
+            case 'catalog.duplicate':
+                result = await this.catalog.duplicate(actor, catalogDuplicate.parse(input));
+                break;
+            case 'catalog.rename':
+                result = await this.catalog.rename(actor, catalogRename.parse(input));
+                break;
+            case 'catalog.create':
+                result = await this.catalog.create(actor, catalogCreate.parse(input));
+                break;
+            case 'editor.list':
+                result = await this.editors.list(actor);
+                break;
+            case 'editor.create': {
+                const p = z.object({ spaceId: id, parentId: id.nullable().default(null), title: z.string().trim().min(1).max(200), editorKey: z.string().max(100) }).strict().parse(input);
+                result = await this.editors.create(actor, p.spaceId, p.parentId, p.title, p.editorKey);
+                break;
+            }
+            case 'item.create':
+                result = await this.spaces.createItem(actor, createItemSchema.extend({ kind: z.enum(['folder', 'page']), artifactId: z.never().optional(), artifactVersionId: z.never().optional() }).parse(input));
+                break;
+            case 'item.edit':
+                result = await this.spaces.editItem(actor, editItemSchema.parse(input));
+                break;
+            case 'page.read':
+                result = await this.pages.read(actor, selection.parse(input).itemId);
+                break;
+            case 'page.export':
+                result = await this.files.exportPage(actor, selection.parse(input).itemId);
+                break;
+            case 'file.list':
+                result = await this.files.list(actor, selection.parse(input).itemId);
+                break;
+            case 'artifact.open':
+                result = await this.files.openArtifact(actor, selection.parse(input).itemId);
+                break;
+            case 'artifact.list':
+                result = await this.files.available(actor, z.object({ page: z.number().int().min(1).default(1) }).strict().parse(input).page);
+                break;
+            case 'artifact.collect': {
+                const p = z.object({ spaceId: id, parentId: id.nullable().default(null), artifactId: id, versionId: id }).strict().parse(input);
+                result = await this.files.collect(actor, p.spaceId, p.parentId, p.artifactId, p.versionId);
+                break;
+            }
+            case 'search': {
+                const p = z.object({ resourceId: id, query: z.string().trim().min(1).max(4000) }).strict().parse(input);
+                result = await this.ai.search(actor, p.resourceId, p.query);
+                break;
+            }
+            default: throw new Error('spaces.action_unknown');
+        }
+        return { success: true, refresh: false, data: result };
+    }
+    async executeViewFileAction(context, viewKey, actionKey, request, file) {
+        if (viewKey !== VIEW || !['file.upload', 'editor.import'].includes(actionKey))
+            throw new Error('spaces.action_unknown');
+        const actor = await this.actor(context);
+        if (actionKey === 'editor.import') {
+            const p = z.object({ spaceId: id, parentId: id.nullable().default(null), editorKey: z.string().max(100) }).strict().parse(request.input);
+            return { success: true, data: await this.editors.create(actor, p.spaceId, p.parentId, file.originalname ?? 'Document', p.editorKey, file.buffer) };
+        }
+        const input = z.object({ spaceId: id, parentId: id.nullable().default(null) }).strict().parse(request.input);
+        return { success: true, refresh: false, data: await this.files.upload(actor, input.spaceId, input.parentId, file.originalname ?? 'file', file.mimetype ?? 'application/octet-stream', file.buffer) };
+    }
+    async resolveViewFile(context, viewKey, request) {
+        if (viewKey !== VIEW)
+            throw new Error('spaces.view_missing');
+        const actor = await this.actor(context);
+        if (request.fileKey.startsWith('item:'))
+            return this.files.current(actor, id.parse(request.fileKey.slice(5)));
+        if (request.fileKey.startsWith('artifact:')) {
+            const { version } = await this.files.openArtifact(actor, id.parse(request.fileKey.slice('artifact:'.length)));
+            if (!version.workspaceFileRef)
+                throw new BadRequestException('spaces.artifact_file_unavailable');
+            return { reference: version.workspaceFileRef, fileName: version.fileName ?? 'artifact',
+                mimeType: version.mimeType ?? 'application/octet-stream', size: version.size ?? undefined };
+        }
+        const version = await this.files.get(actor, id.parse(request.fileKey));
+        return { reference: version.reference, fileName: version.reference.originalName ?? 'file',
+            mimeType: version.reference.mimeType ?? 'application/octet-stream', size: version.reference.size ?? undefined };
+    }
+};
+SpacesView = __decorate([
+    Injectable(),
+    ViewExtensionProvider('spaces.views'),
+    __metadata("design:paramtypes", [SpaceCatalog, SpaceImports, SpaceContent, SpacesService, SpacePages, SpaceAi, SpaceFiles, SpaceEditors, SpaceKnowledge, SpaceAccess])
+], SpacesView);
+export { SpacesView };

package/docs/.mintignore

@@ -0,0 +1,7 @@
+# Mintlify automatically ignores these files and directories:
+# .git, .github, .claude, .agents, .idea, node_modules,
+# README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md
+
+# Draft content
+drafts/
+*.draft.mdx

package/docs/AGENTS.md

@@ -0,0 +1,3 @@
+# Spaces documentation
+
+Document the behavior shipped by this plugin and its required platform capabilities. Keep the distinction between authoring workspace, Assistant file workspace, Space, and Knowledgebase explicit. Do not describe a mock model run as a real model acceptance test. Keep credentials and local deployment identities out of documentation. Use concise MDX pages with frontmatter and update `docs.json` when adding a page.

package/docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mintlify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/README.md

@@ -0,0 +1,3 @@
+# Xpert Spaces documentation
+
+Mintlify documentation for the Spaces plugin. Navigation is defined in `docs.json`; pages cover the product, setup, architecture and validation. Run `npx mint dev` in this directory to preview.

package/docs/architecture.mdx

@@ -0,0 +1,49 @@
+---
+title: "架构和验证"
+description: "Project 存储与成员权限、插件资源和协作能力边界"
+---
+
+## 平台与插件边界
+
+协作空间使用内置 Project Type `platform / space`。Project 管理成员、角色、归档、多 Assistant 绑定和文件工作区；Spaces 插件提供资源树、来源信息、知识库启用入口及 Remote View。
+
+Space 必须绑定 Project，`(tenantId, organizationId, projectId)` 唯一索引保证并发初始化只有一个扩展记录。`SpaceItem.spaceId` 仅关联插件内部的 Space 记录，不是文件存储身份。模块按全新功能开发，不提供独立 Space 卷、Assistant 私有 Space 或旧空间迁移入口。
+
+平台提供 `platform.project.access`、`platform.project.files`、`platform.content.resources`、`platform.content.documents`、协作、知识库及 Artifact 能力。每次资源访问重新检查 Project 成员权限；通过 Assistant 打开时还检查 Assistant 与项目的绑定以及 `spaces` 能力。具有 Assistant 权限本身不授予项目内容权限。
+
+Remote View 使用共享 shadcn/ui 组件、Tailwind 和宿主主题变量。Markdown 由独立 Tiptap 插件编辑；通用审阅与 AI 交互属于 Assistant。当前选择可以传给聊天作为上下文，但不授予权限。
+
+## 文件引用与权威状态
+
+所有空间文件位于 `/project/<projectId>`。正文和附件使用可见的项目相对路径，版本快照使用同一项目下的 `.space-history/<itemId>/<versionId>/<name>`。平台通用文件协议使用 `catalog: 'projects'`、`projectId` 和 `scopeId: projectId`，不包含 `spaceId`。
+
+页面在创建或发现时直接注册 `markdown.tiptap` 平台文档；打开页面只读取已注册文档。没有 Spaces 自有的协作模型、修订/评论/提案表或 `importLegacy` 路径。只读成员发现的新 Markdown 先作为项目文件展示，编辑成员可将其注册为协作文档。
+
+Markdown 文件是可交换内容，平台协作文档维护编辑状态和提交一致性；Space 的正文缓存、哈希和同步状态属于派生信息。写入或投影失败不得回退为仅更新数据库正文。来自其他 Assistant 的项目文件也可以在空间发现。
+
+Artifact 以 `pluginName + resourceType + resourceId` 标识来源，`authorizationProviderKey: "spaces"` 对已有 `resourceId` 附加资源授权，`workspaceFileRef` 定位 Project 中的文件。创建时通过 `scope: { projectId, userId: null }` 显式使用项目共享归属，保留真实操作人用于授权和审计。Provider 不决定归属或列表可见性；列表对当前用户授权后分页，下载同时检查项目权限、资源权限和链接策略。移除独立 Space 卷不移除资源授权、路径校验和项目文件的写保护。
+
+## Runtime 能力边界
+
+- 执行身份共用 `RuntimeActor`；组织内内容要求 `OrganizationRuntimeActor`。`AssistantMiddlewareAccess.assertAccess` 使用显式 `scope`：独立 Assistant 检查发布目录访问权，项目内使用检查当前项目成员及 Assistant 绑定，不额外要求目录或创作工作区可见性；两者均检查有效组织成员和 `provider + requiredFeature`，并与平台 View Middleware Runtime 共用解析规则。
+- View 的组件加载、数据、动作、文件传输与工具调用在入口重新检查能力；空项目状态也需独立 Assistant 授权。身份和项目范围来自可信宿主上下文，不可由 iframe 或工具参数指定。资源授权及协作广播保留项目和操作权限，不逐文档检查功能开关；移除中间件不改变已有文件的项目归属。不存在跨调用授权缓存。
+- `ContentResources.authorize` 负责资源授权，`identities` 子接口提供当前组织身份。Provider 按需组合 `references`、`pages`、`publication`、`locations`，没有对应扩展即可省略。平台文档输入的 `resourceId` 与扩展输入的 `sourceResourceId` 明确区分；子页面创建返回 `documentId`。
+- `ContentEditors`（`platform.content.editors`）负责通用编辑器发现、资源解析与带版本校验的文件读写；平台协议不包含表格、单元格或具体格式的修改指令。
+- `ProjectKnowledge.ensureBinding`（`platform.project.knowledge`）按 projectId 建立一个内置知识库，以平台 `platform.project` 资源策略继承项目权限；Space 表只缓存知识库 ID。已有知识库服务仍要求匹配 actor 的请求/任务上下文。
+- `ProjectFiles` 是显式项目身份的门面；与 `WorkspaceFiles` 共用 Volume 文件读写、路径约束和写入锁，提交前重新检查托管文档写保护。CAS 哈希防止版本覆盖。
+
+## 权限与验证
+
+项目 owner/manager 管理资源，owner/manager/editor 编辑内容，member 只读；归档项目只读。实时会话及后台任务重新校验当前权限。跨项目引用不能通过传入目标项目身份绕过源项目的权限。
+
+交付需联合部署配套平台、SDK 和插件。使用最新实体初始化；本次代码收敛不操作已有开发数据库，不提供历史独立 Space 的升级脚本。
+
+自动化回归覆盖 Project 文件引用重放、跨项目拒绝、只读和撤权拒绝写入、Assistant 解绑，以及正文和版本快照使用相同项目身份。插件还需通过构建、类型检查、元数据检查和 lifecycle harness。浏览器、双用户协作和真实模型验收需要单独执行，不能以单元测试或构建成功代替。
+
+## 编辑器职责边界
+
+- 平台：统一资源引用、Project 与 Assistant 绑定授权、编辑器注册及 Workbench 路由。注册区分文本协作模型与文件编辑器；Markdown 继续使用文本/Yjs 协作管线。
+- Spaces：目录、创建和导入文件、资源权限及版本快照。`editor.describe` 描述当前资源位置；`editor.files` 处理不透明字节与版本，不解析表格。保存时检查资源版本、磁盘哈希和当前权限。
+- Office：XLSX 创建、校验、单元格读取与修改、序列化，以及独立的 `office.files__office.file` Remote View。文件编辑模式按版本保存，冲突时阻止覆盖，不自动合并并发修改；与原生 Office 快照/Yjs 模式分别处理。
+
+Spaces 通过 `workbench.content.resolve({ resourceId, providerKey: 'spaces' })` 解析资源，将返回的 navigation（包括 contentProvider 参数）原样交给当前 Workbench 打开。Spaces 不包含表格编辑 UI。新文档格式通过注册编辑器和独立视图扩展，不需要向平台增加专用格式 RuntimeCapability。

package/docs/collaboration.mdx

@@ -0,0 +1,50 @@
+---
+title: 实时协同编辑
+description: Markdown 双账号同步、并发合并、光标与真实验收
+---
+
+## 已实现的协作链路
+
+同一项目中，具有权限的成员可以通过不同 Assistant 打开同一 Markdown 文档。编辑器使用 Tiptap 与 Yjs；平台管理协作房间、身份、权限、更新日志和文件发布。Spaces 负责内容组织，独立 Markdown 插件负责编辑界面。
+
+- 按文档与 epoch 隔离房间；同一文档不因入口 Assistant 不同而产生副本。
+- 本地增量经宿主 `document.update` 提交，平台持久化后通过 WebSocket 向已授权接收者广播。Yjs 合并并发修改，重复增量不会重复追加正文。
+- 在线人数按账号去重；光标和选区按窗口区分，姓名与颜色来自平台身份。状态不写入正文。
+- 断线后通过状态向量补齐缺失更新。未提交增量保留在当前窗口重试；这不等于关闭浏览器后的持久离线编辑。
+- 保存状态区分「编辑已接收」与「已写入项目文件」。只有文件发布完成才显示已保存；外部文件冲突不能被静默覆盖。
+- 历史恢复或 schema 升级切换 epoch，旧窗口不能覆盖新版本。所有会话和广播仍检查当前项目、Assistant 及资源访问权限。
+
+## 跨账号广播修复
+
+2026-10-23 的真实测试复现了：两个账号能显示在线，但提交编辑会导致另一方断连。进程内广播继承了 HTTP 提交者的 AsyncLocalStorage；文档权限校验把接收者身份与提交者进行比较，误判为身份不匹配。
+
+平台 `CollaborationGateway` 在广播投递边界退出提交者请求上下文，再按各接收者已认证的协作会话逐个授权。普通 HTTP 请求的身份一致性校验保留，撤权接收者仍被断开。Provider 必须使用显式授权上下文中的 actor，不能借用广播提交者的身份或权限。
+
+回归测试覆盖发送方与接收方不同、HTTP 冒用 actor 被拒绝、已撤权接收者不获得广播。网关与协作服务的 6 项定向测试通过。
+
+## 真实验收
+
+两个独立测试账号通过正常登录获取身份，分别经两个已发布 Assistant 打开同一项目文档。测试直接连接实际 API、WebSocket、数据库和项目文件，没有替换协作服务或模拟持久化。
+
+| 场景 | 验证结果 |
+| --- | --- |
+| 双账号进入 | 相同房间、不同身份，双方均看到两人在线 |
+| 同一位置同时输入 | 两份内容通过远端 WebSocket 广播收敛，甲乙输入均保留，重复提交被去重 |
+| 光标与选区 | 对方收到正确账号与 Yjs 相对位置 |
+| 任务清单与公式 | 不同账号的节点修改同时保留 |
+| 断线与重连 | 离线成员移出在线列表，重连补齐遗漏内容，缓存修改重发后收敛 |
+| 未授权账号 | 获取会话与提交更新均被拒绝 |
+| 文件与重开 | 两端内容、重新获取的文档状态和实际 Markdown 文件一致，SHA-256 与平台记录一致 |
+
+这次浏览器自动化连接中断，未完成两个可见浏览器窗口的交互验收；上表为真实协议客户端验收，不能等同于双窗口视觉验收。跨 API 节点和长时间压力测试也不在本次结果中。
+
+## 复现方式
+
+先启动配套平台与插件，准备私有目录中的正常登录助手 `probe.mjs` 和已有测试项目配置 `editor-acceptance-fixture.json`，再从 Markdown 插件目录执行：
+
+```bash
+SPACES_TEST_DIRECTORY=/absolute/path/to/private-test-environment \
+node tests/collaboration.live.mjs
+```
+
+脚本创建独立验收页面，输出七项结果，并将包含实例标识的回执保存到该私有目录。凭据不写入源码、文档或终端结果。可在同一项目的协作空间中打开标题以「双账号实时协作验收」开头的页面继续人工验证。