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

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)。

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.3.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.28.0",
+    "@xpert-ai/plugin-sdk": "^3.28.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.28.0",
+    "@xpert-ai/plugin-sdk": "3.28.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"
+  }
+}