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

package/dist/view.d.ts

@@ -0,0 +1,97 @@
+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 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(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,226 @@
+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 { 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 = ['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 {
+    imports;
+    content;
+    spaces;
+    pages;
+    ai;
+    files;
+    editors;
+    knowledge;
+    access;
+    constructor(imports, content, spaces, pages, ai, files, editors, knowledge, access) {
+        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.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 '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", [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
+```
+
+脚本创建独立验收页面，输出七项结果，并将包含实例标识的回执保存到该私有目录。凭据不写入源码、文档或终端结果。可在同一项目的协作空间中打开标题以「双账号实时协作验收」开头的页面继续人工验证。

package/docs/docs.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Xpert Spaces",
+  "colors": {
+    "primary": "#16A34A",
+    "light": "#07C983",
+    "dark": "#15803D"
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "协作空间",
+        "pages": [
+          "index",
+          "quickstart",
+          "architecture",
+          "insert-menu-plan",
+          "math-subpages",
+          "collaboration",
+          "page-resources-and-connectors",
+          "feishu-document-import"
+        ]
+      }
+    ]
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
+  }
+}

package/docs/feishu-document-import.mdx

@@ -0,0 +1,118 @@
+---
+title: 飞书文档文本副本导入
+description: 通过连接器读取来源，显式复制到项目文件，记录出处与版本
+---
+
+## 本批范围
+
+本批落地第二阶段的只读来源与文本副本导入。入口为协作空间“新建 → 从文档平台导入”。飞书新版文档（`docx`）可列出、按关键词搜索、粘贴链接预览，再导入当前项目文件夹。
+
+这是**文本副本**：图片、附件、公式、表格结构、排版和评论不随副本保留。对话框在导入前显示实际文本及转换提示，用户确认后才保存。原文不会被修改。富文档转换、知识库目录浏览、远端引用、发布与读回、双向同步仍属后续阶段。
+
+## 插件与平台职责
+
+| 层 | 职责 |
+| --- | --- |
+| SDK | 可选 `ConnectorStrategyRuntime.documents` hook；显式 `text/plain` 快照、修订号、内容哈希和提示 |
+| 平台 | `platform.connector.documents` 提供来源目录、搜索、读取；依据当前身份、已发布 Assistant、项目绑定和实时连接状态授权 |
+| 飞书插件 | 在现有 `plugin-lark-cli` 增加独立文档适配模块；调用固定 OpenAPI 域名，保持授权凭据仅在服务端 |
+| Spaces 插件 | 预览、目标文件夹、共享确认、请求幂等、项目 Markdown 文件及来源元数据 |
+| Markdown 插件 | 继续负责 Tiptap/Yjs 编辑；不依赖飞书 SDK，不引入远端协同协议 |
+
+平台目录从已授权的 Assistant 工作区与当前项目连接构建。浏览器传入 `bindingId` 不构成授权；平台先从实时目录中选择，再使用已有 scoped credential API 完成身份、项目、连接状态、刷新与审计检查。此交互 API 不扩大 Agent 执行中的 Connector grants。
+
+当前连接模型只使用平台已有的 **shared** 连接。操作依据该连接授权账户的可见范围，不等于每位项目成员自己的飞书权限。管理员必须按预期团队范围配置连接；个人连接的独立授权和权限交集需要后续单独交付。未连接、不支持文档 hook 的来源不会被当作可读来源。
+
+## 用户流程
+
+1. 在当前文件夹选择“从文档平台导入”。
+2. 选择可用来源。空查询列出云盘根目录；关键词搜索新版文档，当前接口最多取前 199 项。文件夹与知识库导航暂未接入，非根目录文档可用关键词或 `/docx/`、`/wiki/` 链接定位。知识库链接会解析到其指向的新版文档；表格、文件等其他节点类型仍不可导入。搜索和云盘根目录不保证列出个人文档库中的知识库节点，未找到时可粘贴链接。
+3. 选择结果或粘贴新版文档链接，查看文本预览、原文版本和目标项目。
+4. 确认将文本副本共享给项目成员。导入后的内容按项目权限长期保存，飞书撤权不会自动删除已经导入的副本。
+5. 导入后在空间打开，进入同一 Workbench 中的 Markdown 编辑器。列表来源显示“外部文本副本”；更多菜单中的“查看导入来源”显示来源平台、文档 ID、版本、时间、转换提示与可用的原文链接。
+
+空来源、加载中、失败重试和授权失效均有对应界面。搜索结果分页加载并按文档 ID 去重。控件字号和密度沿用宿主主题。
+
+## 一致性与失败恢复
+
+- 读取采用“元数据 → 原始文本 → 元数据”，两次修订号或标题不同则要求重新预览。
+- 导入请求带预览修订号和 SHA-256，服务端重新读取；变化后拒绝导入旧预览。
+- 文件名使用标题与请求 UUID；相同请求 ID 只创建同一份文件，重试不会产生重复副本。请求绑定操作者、来源、预览版本和目标。
+- 使用空间锁与现有发现/移动流程串行；先保存导入意图，再进行文件发布。注册编辑器中断可重试；文件被其他主体修改时保留文件并报冲突。
+- 完成的导入请求仅返回既有副本。后续远端变化不会覆盖已经协同编辑的本地内容。
+- 内容保存在项目 `.md` 文件；`plugin_spaces_item.importOrigin` 保存来源元数据、哈希和幂等凭据，不保存正文、token 或签名下载地址。
+- 导入先编码为字面 Markdown 文本，不将远端 HTML 或链接标记直接作为活动内容。单篇可读取文本上限为 100 KB。
+
+飞书适配器仅接受 HTTPS 的飞书/Lark `/docx/`、`/wiki/` 地址或文档 token；输入 URL 只用于提取文档 ID，绝不直接抓取。请求使用固定 API origin，禁止重定向，有超时和响应大小限制。错误仅带固定错误标识、HTTP 状态与数字业务码，不转发 Axios headers、凭据或原始错误响应。
+
+知识库链接通过飞书当前 `wiki/v2/spaces/node_by_token` 接口解析，使用 `wiki:node:retrieve` 权限。仅接受返回的 `obj_type=docx`，校验节点 ID，并在正文读取后复核映射；元数据保存真实文档 ID，来源链接保留去掉追踪参数的原始知识库 URL。
+
+## 部署
+
+1. 更新平台 plugin-sdk 与 server-ai，重启 API，使 `platform.connector.documents` 生效。
+2. 构建并更新 Spaces 与 Lark CLI 插件。Lark CLI 在 monorepo 中声明 `workspace:^` 依赖，独立部署使用 `corepack pnpm pack` 生成 `.tgz`，再通过平台归档安装接口上传；直接复制源码目录给 npm 安装会报 `EUNSUPPORTEDPROTOCOL`。发布包会把 workspace 范围转换为已发布版本。
+3. 在未启用开发 schema 同步的环境执行 `migrations/20261023-document-import-origin.sql`。
+4. 为所需 Assistant 工作区或项目配置 shared 飞书连接，并在飞书应用与账户中授予读取/搜索文档所需权限。
+
+新 API/SDK 应先于插件升级。仅更新插件会因宿主尚未导出新 capability 而装载失败。
+
+## 验收记录
+
+### 2026-10-23
+
+- Spaces 29 项测试通过，包含并发重复请求、注册中断恢复、源版本变化、撤权、只读/项目外访问、已有文件外部修改保护与字面文本转换。另以实际 Markdown/Tiptap 模型确认 URL、HTML、图片标记与公式样式文本均按文字导入。导入测试使用内存文件与模拟来源，尚不代表真实外部导入。
+- Lark CLI 77 项测试通过，其中新增 5 项覆盖 URL/域名限制、分页与类型过滤、文本快照与修订检查、大小限制、错误脱敏。飞书 HTTP 响应使用模拟数据。
+- 平台相关 3 个套件、105 项测试通过，包含新来源 API 的授权、目录筛选、撤权，以及没有作者工作区的项目 Assistant 连接目录兼容。
+- SDK、两个插件构建和 Spaces 前后端类型检查通过；两个插件生命周期检查通过。Spaces 元数据检查通过；Lark CLI 未声明 package 级 native metadata，静态检查未匹配到条目，其元数据和装载通过生命周期检查确认。
+- 本地 API 已重启加载新能力；Lark CLI 标准发布归档通过真实插件安装接口部署成功。
+- 真实 API 中，项目所有者/编辑者可以查询来源目录，项目外账号被拒绝；伪造连接 ID 的预览被拒绝，畸形输入通过真实 View action 返回 400。当日测试项目没有已授权连接，目录为空。
+- 浏览器已验证 ChatKit Workbench 中的新建菜单、导入对话框、空连接提示与不可提交状态。未将空状态验收记为搜索/预览/导入成功。
+
+**当日待补验**：账户授权、远端搜索/读取、预览后的源变化、导入到真实项目文件并进入 Tiptap、源撤权及不同成员可见范围。当日未对飞书原文执行任何写入。
+
+
+### 2026-10-24：真实账户、导入与协作闭环
+
+- 已由用户完成共享连接授权，真实平台来源目录返回 `active / available`。
+- 经用户授权，在飞书客户端新建了只含验收内容的文档，并看到“已经保存到云端”。该客户端的新文档默认使用 `/wiki/` 地址，因此补充知识库链接解析、节点类型和稳定映射校验。
+- 初次真实飞书节点读取返回 `131006`（资源无权限），原因是客户端身份与连接授权身份不同。适配器将此拒绝映射为 HTTP 403，界面提示核对账号与文档权限。用户随后改用文档创建者账号完成重新授权，连接已恢复 `active`，实际读取成功。没有为解决身份不匹配而扩大文档公开范围或发送邀请通知。
+- 真实搜索请求成功，但精确标题搜索仍未返回个人文档库中的这篇文档。粘贴 `/wiki/` 链接可以解析并读取，直接使用解析后的 `docx` token 读取也得到相同内容哈希。这项结果证明链接读取可用，不代表搜索召回已通过。
+- Lark CLI 81 项测试、Spaces 29 项测试通过；两个插件构建、Spaces 前后端类型检查和两个插件生命周期检查通过。Spaces 静态元数据检查通过，Lark CLI 静态检查未匹配到条目，使用生命周期检查验证装载。Lark CLI 完整 spec 类型检查仍有既有 `lark-bootstrap.connector.spec.ts` 三处旧凭据 fixture 缺少字段；本次文档适配器测试没有类型错误。
+- 更新后的 Lark CLI 发布归档安装成功，Spaces 已刷新；授权完成后重启本地 API，实际加载并使用更新后的插件。
+
+以下检查使用真实飞书账户、专用无敏感内容的测试文档、本地运行的 API、数据库和项目文件系统。没有使用模拟来源替代飞书读取。
+
+| 验收项 | 实际结果 |
+| --- | --- |
+| 浏览器预览与导入 | 在 ChatKit Workbench 内打开导入对话框，粘贴知识库链接，查看真实文本与转换提示，勾选项目共享确认后导入；仅新增一份文档 |
+| 文件与来源 | 文档注册为 `markdown.tiptap`；真实项目 `.md` 文件、来源文档 ID、修订号、内容哈希和原文链接均正确保留 |
+| Workbench 导航 | 点击导入后的条目，在当前 ChatKit Workbench 内打开 Markdown 标签页 |
+| 多成员、多 Assistant | 两个真实平台账号分别经由不同已发布 Assistant，加入同一文档协作房间；在线成员和远端光标可见 |
+| 并发与浏览器输入 | 两个认证客户端在相同位置并发插入，双方收敛；浏览器 Tiptap 输入中文后，两端通过真实 WebSocket 收到更新，无需刷新；重复 update 被识别为幂等 |
+| 断线重连 | 断线后远端在线状态移除；重连取得断线期间的更新，提交缓冲编辑后双方再次收敛 |
+| 持久化 | 两个客户端、重新打开的文档会话、Markdown 读取接口与项目文件正文一致，SHA-256 与登记的文件哈希一致 |
+| 访问边界 | 项目外账号不能预览来源、导入、读取本地文档、创建协作会话或提交编辑；未确认共享的导入返回 400 |
+| 原文独立 | 本地协作前后，飞书原文的版本与哈希保持不变；本地协作不会修改来源元数据 |
+| 来源变化保护 | 随后从飞书客户端手动修改专用测试原文，重新读取确认版本与哈希变化；使用旧预览发起新导入返回 409，不新增文档 |
+| 完成请求重试 | 原文改变后重试原先已完成的导入请求，仍返回已有文档；条目数不变，本地协作后的文件哈希不变，来源仍记录导入时版本 |
+
+协作验收组合是**一个真实浏览器 Tiptap 界面 + 两个真实账号的 API/WebSocket 客户端**，不是两个独立浏览器同时操作的测试，也不包含 AI 模型生成验收。客户端使用平台协作 SDK 和实际 Yjs 文档模型，连接真实服务。脚本位于 `apps/markdown-editor/tests/imported-collaboration.live.mjs`；私有 fixture 指向浏览器已导入的文档，不另建替代页面。运行时通过 `SPACES_TEST_DIRECTORY` 指定私有测试目录，凭据通过本机测试登录设施取得；截图、租户标识和完整回执保留在仓库外。
+
+真实飞书纯文本 API 没有返回测试原文的公式内容，粗体也降为普通文本，与导入前展示的有损转换边界一致。飞书撤权后的实时拒绝在模拟回归中覆盖，本轮没有撤销用户刚完成的连接，故尚未完成该项真实租户验收。
+
+## Remote View 组件规范
+
+导入弹窗使用共享 shadcn/Radix 的 `Dialog`、`DialogHeader`、`DialogFooter`，来源选择使用 `Select`，共享确认使用 `Checkbox` 与关联的 `Label`。不使用原生 select/checkbox，也不覆盖组件的标题字号、内边距、遮罩、边框和按钮外观；这些视觉属性沿用共享组件和宿主 theme variables。插件只约束弹窗可用宽度、滚动区域和内容布局。
+
+Spaces 与 Markdown 的远程资源只加载共享 shadcn 样式中的一次 Tailwind Preflight，插件样式仅补充 theme/utilities，避免第二次 reset 覆盖组件的默认边框规则。来源选择支持方向键、Enter 与 Escape，确认勾选支持空格键；从新建菜单打开的导入弹窗关闭后，焦点返回新建按钮。
+
+## 后续
+
+- 继续补充个人文档库搜索/目录导航、不同来源授权范围和真实撤权验收；富文本块转换另行实现，当前导入闭环以文本副本为准。
+- 有损转换必须持续可见；无法表达的块保留原文或原格式引用，不以纯文本覆盖飞书原文。
+- 发布能力单独设计目标选择、差异预览、版本条件写入及读回；远端协同继续由飞书提供。
+- 其他平台以相同文档来源 hook 接入，Spaces 不判断供应商名称来选择业务逻辑。
+
+接口依据：[飞书文档搜索](https://open.feishu.cn/document/server-docs/docs/drive-v1/search/document-search)、[获取文档基本信息](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/get)、[获取文档纯文本内容](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/raw_content)、[飞书官方云盘技能](https://github.com/larksuite/cli/blob/main/skills/lark-drive/SKILL.md)。
+
+知识库节点解析接口依据：[飞书官方 CLI 节点解析说明](https://github.com/larksuite/cli/blob/main/skills/lark-wiki/references/lark-wiki-node-get.md)。