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

package/docs/index.mdx

@@ -0,0 +1,12 @@
+---
+title: "Assistant 协作空间"
+description: "通过插件给 Assistant 添加共享文档和成果空间"
+---
+
+给 Assistant 的主 Agent 配置 `spaces` 能力并发布后，成员即可在 Workbench 的 Views 中打开协作空间。空间中的页面、文件、评论、AI 修改提案和固定版本成果长期保存，独立于单次聊天。
+
+空间基于类型为“协作空间”的 Project，成员和角色由 Project 统一管理。同项目的多个已绑定 Assistant 共享文件与协作内容；仅拥有 Assistant 权限不会自动获得项目访问权限。
+
+平台提供身份、Assistant 权限与能力校验、协作、文件和 Artifact 基础服务。Spaces 插件提供文档树和资源视图，界面使用 React、shadcn/ui 和 Tailwind。Markdown、Office 等编辑器通过独立 Provider 扩展，通用审阅与 AI 交互属于 Assistant。
+
+开始使用请见 [快速开始](/quickstart)，边界与验收请见 [架构和验证](/architecture)。

package/docs/insert-menu-plan.mdx

@@ -0,0 +1,74 @@
+---
+title: 插入菜单升级计划
+description: 从 ChatGPT Spaces 截图选择可可靠落地的文件协作编辑能力
+---
+
+## 依据与边界
+
+依据 2026-10-23 提供的四张截图分析可见菜单，不将截图中的文案视为已经验证的 ChatGPT 内部行为。尤其“助手说明”的权限、执行方式和自动更新语义，截图不足以确认。
+
+Space 是项目上的协作能力；内容保存在项目文件工作区。Markdown 插件负责编辑，平台负责资源身份、访问校验、协作和版本，Assistant 负责生成与审阅。知识库是文档检索索引，不是正文存储。Markdown 编辑器不依赖 Spaces 服务类，也不新增左侧空间导航。
+
+## 能力取舍
+
+| 截图功能 | 本次选择 | 实现或依赖 |
+| --- | --- | --- |
+| 生成 | 本期：交给 Assistant 撰写 | 保存后追加文档引用到 Assistant 输入框，用户填写要求并发送；编辑器不直接调用模型或覆盖正文 |
+| 创建可视化 | 后续 | 需要有类型的 artifact 引用、版本与沙箱嵌入协议；不能把任意 HTML 当文档节点执行 |
+| 创建子页面 | 已实现 | 独立文件与内容资源，逻辑页面层级另存；见 [公式与子页面](math-subpages) |
+| 图像上传/生成 | 后续 | 先统一项目附件的持久引用、授权预览、导出与清理；生成沿用 Assistant |
+| 文件上传供下载 | 后续 | 空间已有上传，正文仍需附件引用与授权下载协议，不能保存会过期的下载 URL |
+| 助手说明 | 后续讨论 | 先确认产品语义；普通文档内容不能自动提升为 Assistant 系统指令 |
+| 标题 1/2/3、无序/有序列表、引用、代码块、分隔线 | 本期 | 分组插入菜单，保留六点块转换菜单与键盘输入 |
+| 任务清单 | 本期 | Tiptap TaskList/TaskItem，勾选状态经 Yjs 协作，落盘为 GFM 任务列表 |
+| 表格 | 本期 | GFM 表格：表头、正文、增删行列、删除表格；不开放合并单元格、嵌套块和列宽存储等 Markdown 无法无损表达的能力 |
+| 数学公式 | 已实现 | 行内/独立 LaTeX、KaTeX 预览、协作保存与 Markdown 往返；见 [公式与子页面](math-subpages) |
+| 添加页面链接 / 提及页面 | 本期 | 当前项目最近文档选择器与安全 URL 链接；内部链接由宿主授权解析，点击在当前 Workbench 打开 |
+| 提示、强调块 | 本期 | 采用带粗体“提示/重要”标签的标准引用块模板，导出兼容普通 Markdown；不声称复刻 ChatGPT 专有节点 |
+| 提及文件 | 后续 | 共用附件的稳定资源引用，重命名与跨项目权限验证 |
+| 提及聊天 | 后续 | 需要聊天资源引用、消息级定位、访问撤销与导出规则 |
+
+## 本期实施步骤
+
+1. 将插入项和内容构造集中管理；顶部加号打开可滚动的分组菜单，沿用宿主字号、密度和主题。基础插入在当前顶层块之后，不覆盖已有选区；弹窗期间用稳定块 ID 重新定位，目标被协作者删除时明确失败。
+2. 前后端共用 Tiptap schema。加入任务列表和受限 GFM 表格，验证任务状态、表格形状、节点属性和安全链接；不支持的 HTML、图片等仍拒绝导入，保留原文件。
+3. schema 升级到 v2。平台只调用模型显式声明的升级方法；获得写权限并确认文件已物化、无外部冲突后，保留文件字节和块 ID，发布新 epoch，原子归档旧协作房间。旧客户端不能继续写入新版本；失败可恢复，不静默丢弃已接收更新。
+4. 页面链接通过平台授权获取稳定宿主 URL。文档选择器限定当前项目可见资源；点击内部链接复用 `workbench.content.resolve` → `workbench.navigation.open`，不导航到外层宿主。外部链接仅允许 HTTP(S)、mailto 和文内锚点。
+5. “交给 Assistant 撰写”只追加引用到已有输入框，不发送、不替换草稿。待编辑器保存成功才交接。不存在可用 Assistant 时明确报错。
+
+## 验收标准
+
+- 任务勾选、表格单元格、基础块和链接在保存、刷新、导出后保持语义；双客户端更新可合并。
+- 开菜单和弹窗不会丢失插入位置；已有选中文本不被覆盖；目标删除、断线、只读时不误写。
+- 表格增删行列可撤销，复杂结构拒绝保存，不能悄悄扁平化数据。
+- v1 文档升级保留原文件字节、历史与块 ID；并发更新、旧 epoch、外部冲突受到保护。
+- 本地真实浏览器验证菜单、编辑、落盘与刷新；单元测试、类型检查、构建、插件 metadata 和生命周期 harness 均通过。
+
+## 后续实施顺序
+
+1. 平台持久内容引用协议：项目文件、图片、页面、聊天使用显式类型和资源 ID，解析阶段校验权限；不把短期访问凭证写进 Markdown。
+2. 图片与附件：上传复用 Project Files，建立资源引用节点和导出降级；处理取消上传、孤立附件、移动与回收站。
+3. 数学公式已独立扩展并离线渲染；可视化后续设计沙箱和版本约束。
+4. 子页面已基于独立文件和 Space 层级元数据实现；助手说明继续另行设计。
+
+## 交付状态
+
+2026-10-23：本期范围已完成。菜单、基础块、任务清单、表格、引用与 Assistant 交接由 Markdown 插件提供；平台增加无副作用的文档链接命令和显式模型升级接口。基础能力与视图继续分离，后续项不计入本期交付。
+
+### 验证结果
+
+- 51 项定向测试通过：Markdown 插件 15 项、平台文档服务 14 项、宿主链接与命令 22 项。覆盖序列化往返、并发任务/单元格更新、稳定插入锚点、非法结构拒绝、旧客户端隔离、升级恢复及链接命令副作用。
+- Markdown 插件类型检查和构建、宿主 Angular 编译通过；Markdown 与 Spaces 插件 metadata 检查和生命周期 harness 通过。
+- 本地真实后端完成 6 类联调：旧页面资源与原文件、双用户/双 Assistant 共用文档、并发及重试、评论与历史、越权拒绝、版本恢复后的旧 epoch 拒写。
+- v1 文档升级实测：原文件哈希、块 ID 和历史保留，进入 schema v2 与新 epoch；旧客户端请求被拒绝。
+- 浏览器实测任务勾选、表格增删行列与撤销、提示模板、页面选择与打开、自动保存和刷新。最终读取项目文件与文档服务校验哈希一致，保留原段落、任务状态、表格内容及页面链接。
+- 页面链接在当前 ChatKit Workbench 内打开；Assistant 入口追加文档引用并聚焦输入框，没有发送消息。本次验证不包含真实模型生成质量验收。
+
+### 已知限制
+
+- 表格最多 200 行、30 列，仅一个表头；每格单行正文，可含行内格式，不支持合并单元格、嵌套表格或列宽保存。
+- 页面选择器检索当前项目最近 100 份可见文档；全量分页、跨项目引用另行扩展。
+- 只读用户不能执行 schema 升级；旧文档需要有写权限的成员先打开一次。新插件与平台升级接口必须一起部署。
+- 提示和强调块是标准 Markdown 引用模板；生成交由 Assistant。公式与子页面已在 schema v3 中交付，见 [公式与子页面](math-subpages)；图片附件、文件/聊天引用与可视化仍按后续顺序推进。
+
+### 实际界面

package/docs/math-subpages.mdx

@@ -0,0 +1,62 @@
+---
+title: 公式与子页面
+description: 文件优先的公式编辑、页面层级与跨插件扩展设计
+---
+
+## 产品行为
+
+顶部插入菜单新增「数学公式」与「子页面」。编辑器仍保持单文档布局，生成与审阅继续由 Assistant 承担。
+
+公式弹窗包含独立公式块/行内样式、LaTeX 输入、实时预览与错误提示。点击已有公式可以修改或删除；只读成员可以查看源码。新公式插在当前块下方，保留原选区；行内样式放在一个新段落中，也可以在正文通过 `$…$` 输入。代码块内的公式源码保持原文。
+
+创建子页面时输入名称，保存当前文档后创建并在同一 Workbench 打开。子页面上方显示返回父页面入口，父页面正文下方显示子页面列表与创建入口，不增加空间侧边菜单。列表可刷新，以获取其他成员新建的页面。
+
+## 文件与层级
+
+- 每个子页面是独立 `.md` 文件、内容资源和协作文档，保存到创建时父页面所在的项目文件夹。文件名采用「名称--资源 UUID.md」，避免同名覆盖；显示标题不带 UUID。
+- `SpaceItem.parentId` 继续代表文件夹；新增 `parentPageId` 记录逻辑父页面，`childRequestTitle` 记录原创建请求。正文仍保存在项目文件中，知识库继续作为检索索引。
+- 父子关系不是权限继承。所有用户和 Assistant 都必须通过当前项目和资源授权。
+- 父页面改名、移动不改写子页面身份或文件位置；移动整个文件夹仍按文件夹规则处理其中的文件。
+- 删除父页面不级联删除子文件。父页面不可访问时，子页面隐藏父入口，仍能从协作空间打开；恢复父页面后重新显示关系。单独删除子页面会从父列表隐藏，恢复后重新出现。
+- 新建层级最多 32 层，每次展示前 100 个直接子页面。当前不提供重新挂接父页面或子树复制功能。
+- 页面层级属于 Space 元数据，单独下载 Markdown 不包含层级关系；可用「页面引用」在正文中加入可导出的链接。
+
+## 公式持久化与协作
+
+前后端共用 Tiptap Mathematics 节点：`inlineMath`、`blockMath`。行内保存为 `$LaTeX$`，独立块保存为单独两行 `$$` 包围的 LaTeX。渲染采用 KaTeX，字体随插件打包，不依赖 CDN。
+
+每条公式具有稳定 `mathId`；独立公式另有 `blockId`，支持 Assistant 精确提案。弹窗保存前按 ID 重新定位并核对原 LaTeX，发现协作者已修改/删除时拒绝覆盖。实时并发合并沿用 Yjs；普通正文中的复杂行内节点仍不能用纯文本提案粗暴替换。
+
+schema 升级到 v3，沿用已有显式升级机制，支持 v1/v2 无损升级：保留原 CRDT、文件字节、块 ID 和历史，发布新 epoch 隔离旧客户端。既有普通文本不会因升级被自动转换成公式。
+
+单条公式最多 4096 字符，每文档最多 200 条。输入不含外层 `$` 分隔符，行内源码不换行。只支持 KaTeX 的 LaTeX 子集；不执行外部命令，不信任 HTML/URL 指令，限制宏展开和渲染尺寸。语法错误会提示并阻止提交。
+
+## 插件与平台边界
+
+Markdown 仅调用平台 `document.hierarchy` / `document.createChild` 视图动作。平台校验身份、项目和来源资源，将层级查询/创建委托给来源 Provider 的可选 `pageHierarchy` / `createChildPage` 扩展点。未实现此能力的来源不展示子页面创建入口。
+
+Spaces 实现自己的逻辑层级与文件创建。平台复核返回的新资源仍属于当前项目；前端经 `workbench.content.resolve` → `workbench.navigation.open` 打开，不逃逸到外层 Workbench。
+
+创建请求携带固定 UUID。同一个用户、父页面、标题与请求 ID 重试只会继续原创建；不同载荷复用 ID 被拒绝。已写入文件但发布失败时保留创建意图，重试前检查文件哈希，绝不覆盖外部修改。
+
+## 部署与验证
+
+平台 SDK、平台服务、Spaces 和 Markdown 插件须一起更新；生产数据库先执行 `migrations/20261023-subpages.sql`。开发环境可使用宿主实体同步。刷新已打开的编辑器以声明 schema v3；只读成员不能代替写权限成员升级旧文档。
+
+已完成本地部署与验收（2026-10-23）：
+
+- Markdown 19、Spaces 22、平台文档/层级/升级 14，共 55 项定向测试通过；两个插件的类型检查、构建、元数据及生命周期加载检查通过。
+- 5 项真实接口场景通过：公式导入不改原文件、并发重试不重复创建、多 Assistant 共享与越权拒绝、父页面改名/回收/恢复、公式 CRDT 修改物化到文件。
+- 浏览器实测：无效公式阻止保存，行内公式编辑，独立公式预览和插入，子页面创建/编辑/返回父页面，刷新后内容与层级保留。新子页面在当前 ChatKit Workbench 内打开。
+- 服务重启后核对父/子页面的实际 Markdown 文件、内容与哈希一致。已有 v2 文档升级到 v3 后正文和块 ID 不变，旧 schema 客户端请求被拒绝。
+- 本次属于定向验证，未完成平台全库测试；扩展测试范围时遇到既有 `agent-execution.service.ts` 的 TS2589 类型实例化错误，未计为通过。生产发布和跨节点部署不在本次本地验收范围。
+
+可重复运行的接口验收脚本为 Markdown 插件 `tests/math-subpages.live.mjs`，通过 `SPACES_TEST_DIRECTORY` 引用私有测试环境，正常登录后执行；脚本会创建验收页面。凭据与部署 ID 不写入插件文档。
+
+
+
+
+## 技术依据
+
+- [Tiptap Mathematics](https://tiptap.dev/docs/editor/extensions/nodes/mathematics)：行内/块公式与编辑回调。
+- [KaTeX 配置](https://katex.org/docs/options)：预览、访问限制与渲染预算。

package/docs/page-resources-and-connectors.mdx

@@ -0,0 +1,103 @@
+---
+title: 页面资源与文档平台对接计划
+description: 先完成项目文件引用，再以插件接入飞书与其他文档平台
+---
+
+## 目标与边界
+
+写作空间继续使用内置 Project type。项目文件是内容来源，Space 表保存组织与展示元数据，知识库是可重建索引。Markdown 编辑器提供文档编辑与协同，Assistant 负责通用审阅、AI 生成和定时维护。
+
+本计划承接 ChatGPT Pages 调研。图片、附件、页面引用和快速插入优先落地；Task、Prompt、Agent instructions 等能力通过 Assistant 的已有职责实现，不在页面视图复制一套智能体运行系统。
+
+## 分批交付
+
+| 阶段 | 能力 | 验收条件 | 状态 |
+| --- | --- | --- | --- |
+| 1 | 统一资源引用、图片、附件、页面分页选择、`/` 搜索 | 文件往返无损；项目权限；协同；真实接口和浏览器验证 | 已实现；核心验收通过，系统文件选择与下载保存待补测 |
+| 2a | 飞书连接器：列出、搜索、读取、导入文本副本 | 明确转换边界；版本检查；项目权限；来源；真实租户联调 | 已实现，验收见专页 |
+| 2b | 富文档转换、远端引用、发布与读回 | 真实授权账户；权限交集；版本冲突；撤权；读回 | 计划 |
+| 3 | WPS WebOffice 编辑器插件 | 项目文件读写回调、版本、权限、保存回执；真实租户联调 | 计划 |
+| 4 | 增量索引、受控同步、Assistant 维护任务 | 重复事件幂等、删除与撤权、冲突队列、失败重试 | 计划 |
+
+## 第一批设计
+
+### 引用协议与插件边界
+
+平台契约 `ContentReferenceTarget` 显式区分 `image | file | page`，包括 `providerKey` 和 `resourceId`。持久化格式为：
+
+```text
+xpert-resource://v1/{kind}/{providerKey}/{resourceId}
+```
+
+Markdown 图片使用 `![说明](资源 URI)`，附件和页面使用 `[名称](资源 URI)`。名称和图片说明是插入时的快照，资源身份保持稳定。改名与移动后通过资源 ID 找到最新路径；被回收或撤权后显示不可用，恢复后可重新解析。引用不扩大授权。
+
+平台提供 `platform.content.references` Runtime Capability 和可选 provider hooks。每次先校验包含引用的文档，再授权目标；Space provider 限制当前项目，复用 `SpaceFiles` 与 `SpaceDocuments`。编辑器只消费通用契约，不导入 Spaces 实现。将来其他来源可实现相同 hooks。
+
+图片预览地址只存在浏览器内存，Yjs 和 Markdown 中不保存签名 URL 或凭证。File Gateway 在发放访问 grant 与读取文件时重新授权。预览只接受 PNG、JPEG、GIF、WebP 的文件头；SVG/HTML 不作为图片执行。附件强制下载。单文件上限 25 MB。
+
+### 界面
+
+- 顶部插入菜单增加图片、附件与分页页面引用。
+- 图片/附件可上传或从当前项目选择；文件保存在当前文档所在物理文件夹。
+- 上传成功但插入位置失效时保留文件，提示重新选择位置；文件可从空间再次引用。
+- 资源选择器服务端搜索名称，25 条一页，提供加载更多、加载中、失败重试、无结果状态。
+- 左上角文档切换使用同一分页检索，不再受最近 100 条限制。第一批只列出已注册到 Markdown 编辑器的页面。
+- 顶层独立段落输入 `/` 搜索基本块、公式、图片、附件、页面引用；支持方向键、Enter、Escape 和中文输入。正文、代码与 URL 中的斜线不触发。
+- 所有新增控件的尺寸继续继承宿主 root font size 与 density。
+
+### 协同与兼容
+
+Markdown 模型从 schema v3 升级到 v4，只新增资源图片节点。现有 Yjs 数据原样升级，保留文本块锚点，平台使用新 epoch 隔离旧客户端。已有普通网页和页面链接继续有效。图片是可选择/删除/移动的原子节点，说明与资源身份参与 CRDT；不提供图片裁剪和绘图。
+
+对话框持有稳定块 ID，插入前再次定位。`/` 命令执行前重新校验段落内容，协作者改动后中止而不覆盖。外部图片 URL 和原始 HTML 继续拒绝编辑，保留原文件，避免静默丢失内容。
+
+第一批 Markdown 下载保留 Xpert 资源 URI，依赖有权限的 Xpert 环境解析。离线资源打包导出、跨项目引用、聊天引用、图片生成与外部图片抓取不属于本批交付。
+
+## 第二批：飞书
+
+只读文本副本已进入交付，具体行为、边界和验收见 [飞书文档文本副本导入](./feishu-document-import)。
+
+新增独立文档来源适配插件，复用现有连接器授权，不把飞书 SDK 或 token 放入 Spaces View。以只读接入与显式发布起步：
+
+1. 列出/搜索用户可访问的文档和知识空间，保存来源、类型、远端 ID、URL、版本与同步时间。
+2. “引用远端”保留远端作为内容来源；“导入副本”生成当前项目文件并记录出处。两种操作明确区分。
+3. Assistant 可读取授权来源、归纳、形成项目内新稿。发布时显示目标和差异，先检查远端版本，写入后读回校验。
+4. 知识库仅索引授权范围；远端撤权即停止检索与引用，不让服务账号授权扩大给所有项目成员。
+5. 无法在本地无损表示的块保留原文链接/原格式，禁止以纯文本覆盖富文档。
+
+远端协同继续由飞书负责；本地 Tiptap/Yjs 负责项目文件。第一版不承诺两个协同系统自动双向合并。飞书内嵌编辑器需要验证目标租户的 SDK、授权与嵌入条件，不能仅凭 iframe 推定可用。真实验收依赖测试租户应用配置和授权文档。
+
+## 第三批：其他平台
+
+WPS 优先定位 Office 编辑器插件：通过文件、权限和保存回调编辑项目里的 docx/xlsx/pptx，保留 Project 为内容来源。已有 WPS 知识检索连接器不等于 Office 编辑集成。
+
+语雀可作为下一种文档来源接入，复用飞书阶段提炼的读取、导入、发布与版本接口。腾讯文档、钉钉文档先验证目标版本开放接口和租户授权，不提前承诺嵌入编辑或完整双向同步。
+
+## 验收与证据
+
+自动验证包括：身份 URI 与 Markdown 往返、非法图片与协议拒绝、v3 升级、图片与正文并发合并、`/` 输入保护、源文档与目标授权。
+
+真实验证应包括：上传→插入→协同→项目文件落盘→重新读取；分页无重复；改名/移动/回收/恢复；项目外成员、只读成员与撤权后的 grant 失效；浏览器菜单、预览、下载和中文插入。
+
+### 2026-10-23 第一批验收记录
+
+- **插件自动测试**：Markdown 24 项、Spaces 24 项通过；两者 TypeScript 检查、构建、元数据校验和插件生命周期检查通过。生命周期检查仅证明装载与导出契约，不代替业务联调。
+- **平台测试**：资源授权服务 2 项通过；文件访问网关 34 项通过。网关套件遇到仓库现有 `agent-execution.service.ts:12` 的 TypeScript TS2589 深层实例化诊断，第二次执行仅忽略该诊断；未修改仓库测试配置，也不声称完整平台类型检查通过。
+- **真实 API**：`markdown-editor/tests/references.live.mjs` 的 7 个场景通过：上传、游标分页、预览与下载原始字节、双用户/双 Assistant 的资源与正文并发写入、移动/改名/回收/恢复、非法图片与只读/项目外访问拒绝、已发放 grant 在成员撤权后失效。项目文件实际内容与保存哈希一致。
+- **真实 WebSocket**：`markdown-editor/tests/collaboration.live.mjs` 的 7 个场景通过：双用户与双 Assistant 同房间、同位置并发、光标、任务与公式、断线恢复、项目外账号拒绝、最终文件一致。
+- **浏览器已确认**：ChatKit 内的媒体插入菜单、图片和附件选择插入、页面列表 25 条后加载剩余条目、中文检索、`/二级` 转标题、页面引用在当前 Workbench 打开、左上角切回文档。浏览器生成的标题、正文与引用再次从真实项目文件读回，SHA-256 一致。图片预览及附件下载请求返回成功。
+- **尚未确认的系统交互**：浏览器自动化未捕获上传文件选择器和下载完成事件；系统处于锁定状态，无法通过原生文件选择/保存窗口补测。真实 multipart 上传、下载响应及原始字节已验证，但不将其记为浏览器选择文件到保存下载的完整闭环。后续需解锁系统后补测这两步。
+
+真实撤权测试发现并修复了平台 Cookie 文件访问路径遗漏实时授权的问题：现在发放 grant 和读取文件都重新检查当前用户、项目与资源；删除用户、项目撤权、资源移动或回收后旧授权不能继续读取。兼容当前 SDK ALS 与旧 View 服务 CLS 请求上下文，并增加回归测试。
+
+
+飞书、WPS、语雀等后续阶段尚未接入真实租户，本次没有对外部文档执行发布或同步。
+
+## 调研依据
+
+- [ChatGPT Pages](https://learn.chatgpt.com/docs/space/pages)：页面块与插入能力参考。
+- [ChatGPT Space Agents](https://learn.chatgpt.com/docs/space/agents)：维护与运行能力的职责参考。
+- [飞书文档集成方案](https://open.feishu.cn/solutions/detail/docs?lang=zh-CN)：远端文档与嵌入能力的调研入口。
+- [飞书 CLI Markdown 技能](https://github.com/larksuite/cli/blob/main/skills/lark-markdown/SKILL.md)：补丁命令不等于本地 CRDT 同步协议。
+- [WPS WebOffice 回调概述](https://open.wps.cn/documents/app-integration-dev/docs-center/online-preview-edit/callback/summary)：项目文件与编辑器对接参考。
+- [语雀官方 MCP](https://github.com/yuque/yuque-mcp-server)：后续来源插件调研入口。

package/docs/quickstart.mdx

@@ -0,0 +1,17 @@
+---
+title: "快速开始"
+description: "给 Assistant 配置能力，然后在 Workbench 使用空间"
+---
+
+1. 部署配套平台和 SDK，再安装 `@xpert-ai/plugin-spaces` 和 `@xpert-ai/plugin-markdown-editor`。插件含实体与服务，需要按部署回执完成 API 重启；描述符存在不代表已加载。
+2. 创建 Assistant 时，在“Assistant 能力”中勾选“协作空间”，并选择支持工具调用的授权模型。已有 Assistant 可在“设置 → 能力”中启用；Studio 中仍可手动连接 `spaces` 中间件。开关默认关闭，自动配置主 Agent 的空间工具和使用说明，并保留已有能力。
+3. 发布 Assistant，创建类型为“协作空间”的 Project，将 Assistant 绑定到该项目，并通过 Project 成员管理授权协作者。
+4. 在 Assistant 聊天工作台选择该 Project，再从 Views 打开“协作空间”。首次打开时初始化该 Project 的 Space 扩展记录。创建页面、文件夹或导入文档后，在对应编辑器中协作。
+5. 使用 Assistant 聊天调用空间工具，读取、生成或提出文档修改。通用审阅和 AI 交互由 Assistant 承载。
+6. 如需表格，安装 Office Editor 插件提供的 `office.xlsx` 编辑器。导出版本不随之后正文变化。
+
+同一个 Project 绑定的多个 Assistant 共享文件和协作内容。Project 成员权限决定可读、可编辑或可管理；Assistant 的个人文件隔离设置不改变 Project 文件归属。撤销项目权限或解除 Assistant 绑定后，相应访问失效。
+
+平台和 SDK 必须包含配套能力。所有空间必须绑定 Project；不创建独立 Space 文件卷，不提供旧空间迁移入口。模型和连接密钥沿用平台配置，不进入插件或浏览器。
+
+快捷开关来自插件注册的 Assistant Capability Provider，平台不硬编码 Spaces。启用能力只组合 Assistant 配置，不自动创建 Project、复制文件或扩大成员权限。通过能力开关添加的配置可在设置中关闭；Studio 原有配置按平台规则保留，已被手动修改的托管配置会提示冲突。

package/migrations/20261023-document-import-origin.sql

@@ -0,0 +1,4 @@
+-- Additive metadata only. Document bytes remain in the Project workspace.
+BEGIN;
+ALTER TABLE plugin_spaces_item ADD COLUMN IF NOT EXISTS "importOrigin" jsonb;
+COMMIT;

package/migrations/20261023-subpages.sql

@@ -0,0 +1,6 @@
+-- Additive migration. Logical page ancestry does not replace file-folder parentId or project ACLs.
+BEGIN;
+ALTER TABLE plugin_spaces_item ADD COLUMN IF NOT EXISTS "parentPageId" uuid;
+ALTER TABLE plugin_spaces_item ADD COLUMN IF NOT EXISTS "childRequestTitle" varchar(200);
+CREATE INDEX IF NOT EXISTS "IDX_space_page_parent" ON plugin_spaces_item ("tenantId", "organizationId", "spaceId", "parentPageId");
+COMMIT;

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@xpert-ai/plugin-spaces",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "migrations",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "corepack pnpm run build:ui && node scripts/build.mjs && tsc -p tsconfig.json && node scripts/build.mjs --check",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.remote.json",
+    "test": "tsx --test tests/*.test.ts",
+    "verify:dist": "node scripts/build.mjs --check",
+    "prepack": "npm run verify:dist",
+    "test:live": "node scripts/project-live-acceptance.mjs",
+    "build:ui": "corepack pnpm --filter @xpert-ai/plugin-shadcn-ui build"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1",
+    "yjs": "13.6.31"
+  },
+  "description": "Assistant collaboration capability with a shadcn/Tailwind Workbench Remote View",
+  "xpert": {
+    "plugin": {
+      "level": "system",
+      "artifactNamespace": "spaces",
+      "runtimePolicy": {
+        "install": "restart",
+        "update": "restart",
+        "uninstall": "restart"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.6",
+    "@nestjs/typeorm": "^11.0.0",
+    "@xpert-ai/contracts": "^3.27.0",
+    "@xpert-ai/plugin-sdk": "^3.27.0",
+    "typeorm": "^0.3.24",
+    "zod": "3.25.67"
+  },
+  "devDependencies": {
+    "@langchain/core": "0.3.72",
+    "@nestjs/common": "11.1.6",
+    "@nestjs/core": "11.1.6",
+    "@nestjs/typeorm": "^11.0.0",
+    "@tailwindcss/cli": "4.3.2",
+    "@types/node": "^22.13.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@xpert-ai/contracts": "3.27.0",
+    "@xpert-ai/plugin-sdk": "3.27.0",
+    "@xpert-ai/plugin-shadcn-ui": "workspace:*",
+    "esbuild": "0.28.1",
+    "playwright-core": "^1.55.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-markdown": "10.1.0",
+    "reflect-metadata": "0.2.2",
+    "socket.io-client": "4.8.1",
+    "tailwindcss": "4.3.2",
+    "tsx": "4.20.6",
+    "typeorm": "^0.3.24",
+    "typescript": "5.9.3",
+    "zod": "3.25.67"
+  }
+}