Skip to content

feat: add transport-independent Yjs collaboration - #363

Open
peanut4556 wants to merge 1 commit into
floatboatai:mainfrom
peanut4556:feat/add-crdt-collaboration
Open

peanut4556 wants to merge 1 commit into
floatboatai:mainfrom
peanut4556:feat/add-crdt-collaboration

Conversation

@peanut4556

@peanut4556 peanut4556 commented Sep 22, 2026 •

Copy link
Copy Markdown

Summary / 摘要

新增可选的 Yjs 实时协作编辑包,为 Markdown 编辑器提供增量同步、离线合并、独立撤销/重做和远端光标能力。

Motivation / 背景与动机

通过整篇 Markdown 替换进行同步会丢失并发编辑,并将远端修改混入本地撤销历史。本次实现使用 Yjs CRDT 同步增量操作,同时保持 Nexus 作为无头 Markdown 编辑器引擎的定位。

  • Issue: 暂无关联 issue。
  • Roadmap (docs/ROADMAP.md): 第 18 项 Realtime collaboration (OT / CRDT)。
  • OpenSpec change: add-crdt-collaboration,位于 openspec/changes/add-crdt-collaboration/。

Changes / 变更内容

  • packages/core:
    • 新增通用 editorHistory 后端,用于接管公开 undo/redo API;未配置时保留原有行为。
    • 已提交的远端事务绕过 Nexus 本地拒绝/改写过滤器,同时继续通知监听器。
    • 新增 livePreview.tableMode: "source",保留表格 Markdown 源码编辑及其他节点的实时预览。
    • 同步公开类型、README 和核心回归测试。
  • packages/plugin-*:
    • 新增 @floatboat/nexus-plugin-collab 和 createCollaborativeEditor()。
    • 将编辑器与宿主拥有的 Y.Text 双向绑定,同步增量编辑。
    • 提供每编辑器独立的选择性撤销/重做,以及基于 CRDT 相对位置的选区恢复。
    • 提供可选 awareness 远端光标、选区、姓名和颜色。
    • 处理监听器及历史资源清理、Unicode 边界和 CRLF 保留。
    • 新增双副本示例,支持暂停连接、离线编辑、重连合并及分别撤销/重做。
    • 补充接入文档、构建后公开类型检查和协作测试。
  • apps/electron-demo:
    • 本次未修改;协作示例位于 packages/plugin-collab/examples/。
  • openspec/:
    • 新增提案、设计、任务清单,以及协作和核心扩展规范。

Testing / 测试

  • pnpm test passes / 全绿:全仓库 72 个测试文件、932 个测试用例通过。
  • Affected packages build (pnpm build) / 受影响包构建通过:工作区包构建通过。
  • New / updated vitest cases / 新增或更新的 vitest 用例:
    • 并发插入、重叠删除、离线编辑和状态向量重连。
    • 乱序、重复消息及四副本确定性编辑调度。
    • 本地撤销隔离、远端编辑后的选区恢复、快捷键和原生历史事件。
    • 本地过滤器、远端事务投影、只读副本和静默替换。
    • Unicode 边界、CRLF、表格源码模式、awareness 和重复销毁。
    • 核心默认历史行为及表格源码模式回归。
  • Manual UI check in electron-demo / electron-demo 手动验证:已完成。

其他已通过检查:

  • pnpm typecheck
  • pnpm check:api
  • pnpm --filter @floatboat/nexus-plugin-collab build:demo
  • openspec validate add-crdt-collaboration --strict
  • git diff --check

验证使用 pnpm 9.15.4。示例构建存在大体积 chunk 提示;尚未完成交互式浏览器验收。

Compliance / 合规自检

  • CLA signed — first-time contributors will be prompted automatically by the CLA bot / 首次贡献者按 CLA 机器人提示签署
  • AI disclosure: the functional code in this PR is not primarily generated by AI. AI assistance, if any, is described below.
    AI-assisted notes / AI 使用说明:
    本次部分功能实现、测试和文档由 OpenAI Codex 根据需求生成并迭代,包含AI 生成的功能代码。
  • New dependencies (if any) listed with license & rationale (none if blank):
    - yjs@^13.6.27 — MIT — peer dependency;提供 CRDT 文本、更新编码、状态向量、相对位置及选择性撤销。自行实现会引入并发收敛与历史恢复的复杂性。
    - y-protocols@^1.0.6 — MIT — peer dependency;提供 awareness 状态协议,避免自定义一套与常见 Yjs provider 不兼容的协议。
    - 新包复用已有工作区依赖:@codemirror/commands@^6.8.1、@codemirror/state@^6.6.0、@codemirror/view@^6.41.0 和 @floatboat/nexus-core@workspace:*,用于编辑器状态、视图、历史及核心 API 集成。
    - vite@^6.3.0 — MIT — 开发依赖,仅用于运行和构建双副本示例。
    - 新依赖仍需维护者批准。
  • No build artifacts committed (dist/, dist-electron/, compiled .js from .ts) / 未提交构建产物
  • No secrets / .env / personal vault data committed / 无敏感信息

Checklist / 自检清单

  • Title follows Conventional Commits / 使用 feat: add transport-independent Yjs collaboration;按 CONTRIBUTING.md §2 省略 scope。
  • Public API changes update package README / types — 已同步核心与协作包 README、公开类型和 API 检查。
  • Touched live-preview-table.ts → walked through the 12 Table Widget rules in CLAUDE.md / 不适用:未修改该文件。
  • New capability / breaking change → OpenSpec proposal linked / 已附 add-crdt-collaboration;维护者批准尚待完成。
  • Change aligns with project scope (GOVERNANCE.md §4) / 实现编辑器级协作原语;网络服务、账号、鉴权和持久化留给宿主。

Screenshots / Recordings · 截图或录屏 (UI changes)

cb4e0a40417d5a991b7347f5ed229479

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.


ljxxy seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants