JoySpace Publisher 插件安装使用说明

JoySpace Publisher 让你在 Obsidian 中写笔记，再将笔记发布到 JoySpace，方便同事在线阅读。修改本地笔记后，可以继续更新同一篇 JoySpace 文档；也可以把 JoySpace 文档导入自己的笔记库。

可以用它做什么

所有发布、更新和导入都由你手动触发。插件不会在编辑时自动同步。

安装与首次准备

1. 安装插件

在插件市场搜索 joyspace publisher 即可安装

2. 准备登录状态和本地环境

• 发布新文档、导入文档： 需要 Python 3 和 browser_cookie3，并在浏览器中登录 JoySpace。推荐使用 Chrome 登录 joyspace.jd.com，确认能正常打开自己的文档，并具备目标位置的访问或创建权限。

• 更新已有页面： 还需要本机安装 WebCLI，并完成它的登录及浏览器连接准备。

插件会自动查找 Python 和 WebCLI 的路径，不会自动安装或更新这些依赖。还没准备好时，可按文末的 [[#扩展阅读：运行环境、原理与接口|运行环境说明]] 操作。

3. 检查插件设置

进入 设置 → JoySpace Publisher，点击 检测本地运行环境 → 重新检测环境。

确认 Python 路径已填写；需要更新页面时，还应确认 WebCLI 路径可用。

首次使用可以保持默认值：新文档发布到 私人空间根目录，成功后自动打开 JoySpace。

日常使用

发布一篇笔记，之后持续更新

1. 在 Obsidian 中打开要发布的 Markdown 笔记。
2. 点击左侧的 云朵上传按钮，或打开命令面板，执行 JoySpace Publisher： 发布/更新当前文档到 JoySpace。
3. 等待完成提示；默认会使用系统浏览器打开对应的 JoySpace 页面。

同一个按钮会根据笔记是否已经绑定 JoySpace 页面决定下一步：

页面标题使用笔记文件名，不含 .md。 正文中的一级标题和其他标题层级都会保留。重命名笔记后再次发布，也会更新线上页面标题。笔记开头的 YAML 属性不会作为正文上传。

插件会在笔记属性中保存页面绑定和发布记录，通常无需手动修改。保留这些属性，后续才能更新原页面。

如果你只想更新已发布的页面，可以执行 更新当前文档到已绑定 JoySpace 页面。未绑定的笔记会提示先发布，不会通过这条命令新建页面。

把主笔记和它引用的笔记一起发布

例如，《项目说明》引用了《设计方案》和《会议纪要》，希望同事在线阅读时也能点开它们：

1. 打开《项目说明》。
2. 在命令面板执行 JoySpace Publisher： 发布/更新当前笔记及一层引用到 JoySpace。
3. 插件先发布或更新《设计方案》《会议纪要》，再处理《项目说明》。
4. 线上《项目说明》中的引用会变成可点击的 JoySpace 链接。

例如，本地的 [[设计方案]] 或 [[设计方案|查看设计]]，会在上传副本中变成指向对应 JoySpace 页面的普通链接。本地正文仍保留原来的 Obsidian 双链。

使用时留意以下范围：

• 只处理一层引用： 如果《设计方案》还引用了《素材清单》，不会继续上传《素材清单》。同一篇笔记被重复引用时只处理一次。

• 支持双链、带别名的双链、Markdown 笔记链接和笔记嵌入。笔记嵌入会变成普通链接；指向标题或块的引用会链接到整篇页面。

• 外部网址、当前笔记自身、图片和其他附件不作为引用笔记上传。

• 每篇笔记使用自己的发布位置；未单独配置时使用插件默认位置，不会继承主笔记的位置。

执行过这条命令后，插件会记住主笔记的引用转换方式。以后点击普通发布按钮，仍会将引用转换为已绑定的 JoySpace 链接，但不会顺带更新引用笔记的内容。新增引用，或引用笔记也有修改时，请再次执行“一层引用”命令。

找不到引用笔记时，操作会在上传前停止。中途某篇上传失败时，后续引用和主笔记不会继续发布；已成功处理的页面会保留绑定，重试时复用。

决定新文档发布到哪里

大部分笔记放在同一位置：在设置中填写 目标 JoySpace 页面。

常用链接形式：

1
2
3
文档：https://joyspace.jd.com/pages/<page-id>团队：https://joyspace.jd.com/teams/<team-id>目录：https://joyspace.jd.com/teams/<team-id>/<folder-id>

只有某一篇笔记需要放到别处：在它开头的 YAML 属性中添加：

1
joyspace-target-page-url: "https://joyspace.jd.com/teams/<team-id>/<folder-id>"

笔记中的非空配置优先于插件设置；留空时继续使用插件默认位置。

这些设置用于决定新建页面的位置。已经绑定的笔记仍更新原页面；修改发布位置不会把原页面搬到新目录，也不会将填写的目标文档变成更新对象。

把 JoySpace 文档导入 Obsidian

1. 先在 Obsidian 中打开目标文件夹内的一篇笔记。
2. 执行 JoySpace Publisher： 从 JoySpace 链接拉取文档到当前目录。
3. 粘贴文档链接，例如 https://joyspace.jd.com/pages/<page-id>。
4. 点击 拉取到当前目录。

导入文件会保存在当前打开笔记所在的文件夹；没有打开笔记时，保存到笔记库根目录。它不是按左侧文件列表中选中的文件夹决定位置。

插件会以线上标题生成文件名，遇到同名文件时自动增加  (1)、 (2) 等后缀，保留已有文件。重复导入同一链接也会创建新文件。

目前只支持 JoySpace 普通文档，不支持把在线表格、幻灯片等作为文档导入。标题、段落、列表、表格、代码块、引用等内容会转换为 Markdown；复杂排版不保证完全一致。图片和附件保留链接，不会下载到本地。

导入的笔记会记录原页面的绑定。之后在这篇笔记上执行发布或更新，会更新原来的 JoySpace 文档。

图片和附件怎么处理

插件目前不会将本地图片或附件自动上传到 JoySpace，“一层引用”功能也不包含附件。

• 、![](attachments/截图.png) 等本地图片引用，无法仅靠这个插件变成可在线查看的图片。

• 如果希望笔记中的图片也能供同事阅读，可先使用组织允许的图床，将图片替换为在线链接，再发布笔记。PicGo 配合 Obsidian 图片上传插件是一种可选方案，JoySpace Publisher 本身不负责图床配置。

普通单篇发布也不会主动发布或转换所引用的其他笔记；需要让同事点开这些笔记时，请使用“一层引用”命令。

常见问题

还是出现重复页面，或复制笔记后更新了同一个页面？

插件依靠笔记属性里的 joyspace-page-id 识别绑定，不会根据文件名寻找线上文档。旧版本创建的页面如果没有绑定记录，再次发布可能新建页面；复制笔记时若连同绑定属性一起复制，两篇笔记则会指向同一个页面。

如果确实需要发布一份独立副本，可在副本中移除 joyspace-page-id、joyspace-url、joyspace-sync-hash、joyspace-synced-at 后再发布。

提示缺少 Python 或 browser_cookie3？

检查设置里的 Python 路径，并为这个 Python 环境安装 browser_cookie3，然后重新检测。具体命令见文末。

新建文档正常，更新却失败？

新建与更新使用的本地工具不同。检查 WebCLI 可执行文件 是否正确，并确认 WebCLI 的浏览器连接、JoySpace 登录状态和页面编辑权限。仅检测到 Python 并不足以执行更新。

提示无法读取登录状态或没有权限？

先在 Chrome 中重新登录 JoySpace，并打开目标页面确认权限。代码优先读取 Chrome 的京东登录状态，读取不到时再尝试其他受支持浏览器；使用多个账号时，也应确认 Chrome 中登录的是要用于发布的账号。

提示“页面已创建，但正文回读验证失败”？

先打开提示中对应的远端页面查看。插件会先保存已创建页面的绑定，再报告回读失败；保留绑定后重试会走更新流程。若同时提示本地属性保存失败，需先核对远端页面并恢复绑定，避免重复创建。

提示“找不到引用笔记”或“引用笔记尚未绑定”？

确认本地引用能在 Obsidian 中打开；新增或尚未发布的引用笔记，请用“一层引用”命令一起处理。若提示笔记索引尚未就绪或与正文不同步，稍等片刻再试。

扩展阅读：运行环境、原理与接口

以下内容用于首次配置、排查问题或了解实现细节，日常使用不需要逐项阅读。

本地依赖怎么准备

Python 与登录状态读取依赖

在终端确认 Python 可用，然后手动安装依赖：

1
2
3
python3 --versionpython3 -m pip install --user browser_cookie3python3 -c "import browser_cookie3; print(browser_cookie3.__file__)"

如果插件设置使用了其他 Python 路径，请将命令中的 python3 换成该路径，确保依赖安装在同一个环境中。macOS 首次读取浏览器登录信息时，可能需要授予钥匙串访问权限。

WebCLI

更新已绑定页面依赖 WebCLI。可参考 WebCLI 安装说明（需 JoySpace 访问权限），按其要求准备 Node.js/npm、安装 WebCLI，并完成 Browser Bridge 浏览器扩展配置及登录。插件当前没有单独的 Node 路径设置。

可在终端通过 which python3、which webcli 核对路径，通过 webcli --json doctor 检查浏览器连接。更换运行环境后，回到插件设置重新检测。

其他设置

• 租户编码： 默认 CN.JD.GROUP；也提供 TH.JD.GROUP、ID.JD.GROUP、SF.JD.GROUP，按实际账号所属租户选择。

• 发布或更新后打开 JoySpace： 默认开启。关闭后仍可发布，只是不自动打开浏览器。

笔记中的 JoySpace 属性

这些属性位于笔记开头的 YAML 区域，发布时会从上传正文中去除。本地正文和双链会保留，插件会写入或更新相关属性。

发布与导入如何完成

• 新建页面： 读取当前笔记 → 准备上传副本 → 通过 Python 读取浏览器登录信息 → 调用 JoySpace 接口创建页面 → 回读检查是否已有标题和正文 → 保存发布记录。回读检查不等同于逐字比对正文。

• 更新页面： 准备上传副本 → 调用本机 WebCLI 写入新正文、清理旧正文并更新标题 → 回读核对页面 ID 和标题。此流程包含多步写入，发生异常时页面可能已部分变化，应先打开远端检查。

• 导入文档： 读取浏览器登录信息 → 获取普通文档内容 → 转换为 Markdown → 保存为新的本地文件。

Python 读取到的 Cookie 仅用于 JoySpace 请求认证，不会写入插件设置或笔记。发布会将笔记标题和正文发送到 JoySpace；使用一层引用命令时，也会发送这些直接引用笔记的内容。

依赖哪些接口

更新已有页面由 WebCLI 执行，其内部接口不在插件中直接维护。

本说明核对的代码包括 manifest.json、src/main.js、src/domain/note-references.js、src/services/import-markdown-doc.mjs 和 src/services/pull-joyspace-doc.mjs。