插件应用市场
markdown2kdocs
上传markdown到金山文档并转为智能文档
# markdown2kdocs 操作指南
uTools 插件（仅 Windows）：把本地 Markdown 笔记**保真上传**为金山文档智能文档（.otl）。
配图、绘图（Excalidraw / mermaid）、代码块在云端完整呈现；同一文件重复上传只覆盖更新云端
同一篇文档。
变更历史见 [RELEASE_NOTES.md](./RELEASE_NOTES.md)。
## 一、环境准备（一次性）
| 依赖 | 用途 | 检查 / 安装 |
|------|------|------------|
| kdocs-cli + 认证 | 上传通道 | 见下方 [kdocs-cli 安装](#kdocs-cli-安装) |
| Microsoft Edge | 渲染 Excalidraw / mermaid 为图片 | 系统自带即满足；未安装时绘图渲染自动降级（通知会说明），不影响其他功能 |
| uTools 开发者工具 | 加载插件 | 加载本目录 `plugin.json` |
### kdocs-cli 安装
下载对应平台的安装包，解压后将可执行文件放入 PATH 目录，终端执行 `kdocs-cli version` 验证，
再执行 `kdocs-cli auth login` 完成认证（浏览器登录，token 存系统密钥链，插件不持有）。
本插件仅 Windows，常用下载地址（v2.6.13）：
**Windows amd64：**
```
https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-windows-amd64.zip
```
**Windows arm64：**
```
https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-windows-arm64.zip
```
其他平台（在别的机器上使用 kdocs-cli 时）：
| 平台 | 下载地址 |
|------|---------|
| Linux amd64 | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-linux-amd64.tar.gz` |
| Linux arm64 | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-linux-arm64.tar.gz` |
| macOS amd64（Intel） | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-darwin-amd64.tar.gz` |
| macOS arm64（Apple Silicon） | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-darwin-arm64.tar.gz` |
**使用 AI Agent 的机器**（如装有 Claude Code），可直接复制下面这段话让 Agent 代为安装并认证：
> https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/kdocs.zip 下载 zip 包并 unzip 解压，帮我安装这个 skill，然后运行 kdocs-cli auth login 完成认证。
## 二、日常使用
1. 资源管理器选中 `.md` 文件 → 按中键呼出超级面板 → 「上传到金山文档」；
或 uTools 搜索框输入「md传kdocs」→ 选择文件。
2. 等待完成通知（含绘图渲染时每张图约 1~2 秒，长文多图请耐心）。
3. 通知内容解读：
- 「已上传到「utools上传」：xxx.md」/「已覆盖更新云端文档：xxx.md」——成功；
- 「链接已复制到剪贴板」——直接粘贴即可分享；
- 「⚠ …」——警告行（见 [第五节](#五通知警告解读)），上传已成功，按提示处理即可；
- 「⚠ 自动验证未通过（图片块 x/y）」——已上传但云端实际块数与预期不符，点开链接人工确认。
## 三、Markdown 内容支持全景
| 你笔记里写的内容 | 上传后在金山文档的表现 |
|------------------|------------------------|
| `` 相对路径图片 | 读取本地文件内嵌为图片（md 所在目录解析） |
| `` 绝对路径图片 | 同上；图片在 md 目录外时通知中会有可见性 ⚠（正常安全提示） |
| `![[a.png]]` Obsidian 嵌入 | 按 Obsidian 语义查找：同目录 → md 子目录树 → **整个 vault**（自动向上探测 `.obsidian`），找到即内嵌 |
| `![[a.png|800]]` 带尺寸 | 同上，`\|800` 忽略 |
| `![[架构.excalidraw.md]]` Excalidraw 绘图 | **本地渲染为 PNG 图片**（自动解压绘图数据，无需开 Auto-export） |
| ` ```mermaid ` 代码块 | **本地渲染为 PNG 图片**（白底 2 倍分辨率；渲染失败回退云端渲染） |
| ` ```语言 ` 普通代码块 | 云端原生代码块组件 |
| `` 远程图片 | 透传，云端原生渲染 |
| `![[另一篇笔记]]` 笔记嵌入 | 原样保留（不支持嵌套展开） |
## 四、大小限制
- **正文总量上限 8MB**（2026-09-11 云端实测；图片内嵌后按 base64 放大约 1.33 倍计入）。
- 单张图片文件超过 8MB 时跳过该图并在通知中说明（避免撑爆正文），其余正常上传。
- 超限处理建议：压缩 / 裁剪大截图（Obsidian 粘贴的 PNG 截图常在 1~3MB），或拆分文档。
## 五、通知警告解读
| 通知中的 ⚠ | 含义 | 处理 |
|-----------|------|------|
| 图片无法读取，保留原引用 | 引用的图片文件不存在 / 无权限 | 核对路径 |
| Obsidian 引用无法定位图片 | 三层查找（同目录/子树/vault）都没找到该文件名 | 核对文件名，确认 md 在 vault 内 |
| 图片过大（N 字节，上限 …） | 单图超过 8MB | 压缩图片 |
| Excalidraw 嵌入渲染失败（原因） | 源文件缺失 / 格式异常 / Edge 超时 | 按原因处理；重试通常可解决偶发超时 |
| mermaid 块 渲染失败（原因） | mermaid 语法错误等 | 修正语法；失败已回退云端渲染，可能仍可显示 |
| 已内嵌 md 目录外的本地图片 | 安全可见性提示（引用了 md 目录之外的本地图片并已上云） | 属预期行为，知悉即可 |
uTools 插件（仅 Windows）：把本地 Markdown 笔记**保真上传**为金山文档智能文档（.otl）。
配图、绘图（Excalidraw / mermaid）、代码块在云端完整呈现；同一文件重复上传只覆盖更新云端
同一篇文档。
变更历史见 [RELEASE_NOTES.md](./RELEASE_NOTES.md)。
## 一、环境准备（一次性）
| 依赖 | 用途 | 检查 / 安装 |
|------|------|------------|
| kdocs-cli + 认证 | 上传通道 | 见下方 [kdocs-cli 安装](#kdocs-cli-安装) |
| Microsoft Edge | 渲染 Excalidraw / mermaid 为图片 | 系统自带即满足；未安装时绘图渲染自动降级（通知会说明），不影响其他功能 |
| uTools 开发者工具 | 加载插件 | 加载本目录 `plugin.json` |
### kdocs-cli 安装
下载对应平台的安装包，解压后将可执行文件放入 PATH 目录，终端执行 `kdocs-cli version` 验证，
再执行 `kdocs-cli auth login` 完成认证（浏览器登录，token 存系统密钥链，插件不持有）。
本插件仅 Windows，常用下载地址（v2.6.13）：
**Windows amd64：**
```
https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-windows-amd64.zip
```
**Windows arm64：**
```
https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-windows-arm64.zip
```
其他平台（在别的机器上使用 kdocs-cli 时）：
| 平台 | 下载地址 |
|------|---------|
| Linux amd64 | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-linux-amd64.tar.gz` |
| Linux arm64 | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-linux-arm64.tar.gz` |
| macOS amd64（Intel） | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-darwin-amd64.tar.gz` |
| macOS arm64（Apple Silicon） | `https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/releases/kdocs-cli-2.6.13-darwin-arm64.tar.gz` |
**使用 AI Agent 的机器**（如装有 Claude Code），可直接复制下面这段话让 Agent 代为安装并认证：
> https://wpsai.wpscdn.cn/skillhub/pro/v2.6.13/kdocs.zip 下载 zip 包并 unzip 解压，帮我安装这个 skill，然后运行 kdocs-cli auth login 完成认证。
## 二、日常使用
1. 资源管理器选中 `.md` 文件 → 按中键呼出超级面板 → 「上传到金山文档」；
或 uTools 搜索框输入「md传kdocs」→ 选择文件。
2. 等待完成通知（含绘图渲染时每张图约 1~2 秒，长文多图请耐心）。
3. 通知内容解读：
- 「已上传到「utools上传」：xxx.md」/「已覆盖更新云端文档：xxx.md」——成功；
- 「链接已复制到剪贴板」——直接粘贴即可分享；
- 「⚠ …」——警告行（见 [第五节](#五通知警告解读)），上传已成功，按提示处理即可；
- 「⚠ 自动验证未通过（图片块 x/y）」——已上传但云端实际块数与预期不符，点开链接人工确认。
## 三、Markdown 内容支持全景
| 你笔记里写的内容 | 上传后在金山文档的表现 |
|------------------|------------------------|
| `` 相对路径图片 | 读取本地文件内嵌为图片（md 所在目录解析） |
| `` 绝对路径图片 | 同上；图片在 md 目录外时通知中会有可见性 ⚠（正常安全提示） |
| `![[a.png]]` Obsidian 嵌入 | 按 Obsidian 语义查找：同目录 → md 子目录树 → **整个 vault**（自动向上探测 `.obsidian`），找到即内嵌 |
| `![[a.png|800]]` 带尺寸 | 同上，`\|800` 忽略 |
| `![[架构.excalidraw.md]]` Excalidraw 绘图 | **本地渲染为 PNG 图片**（自动解压绘图数据，无需开 Auto-export） |
| ` ```mermaid ` 代码块 | **本地渲染为 PNG 图片**（白底 2 倍分辨率；渲染失败回退云端渲染） |
| ` ```语言 ` 普通代码块 | 云端原生代码块组件 |
| `` 远程图片 | 透传，云端原生渲染 |
| `![[另一篇笔记]]` 笔记嵌入 | 原样保留（不支持嵌套展开） |
## 四、大小限制
- **正文总量上限 8MB**（2026-09-11 云端实测；图片内嵌后按 base64 放大约 1.33 倍计入）。
- 单张图片文件超过 8MB 时跳过该图并在通知中说明（避免撑爆正文），其余正常上传。
- 超限处理建议：压缩 / 裁剪大截图（Obsidian 粘贴的 PNG 截图常在 1~3MB），或拆分文档。
## 五、通知警告解读
| 通知中的 ⚠ | 含义 | 处理 |
|-----------|------|------|
| 图片无法读取，保留原引用 | 引用的图片文件不存在 / 无权限 | 核对路径 |
| Obsidian 引用无法定位图片 | 三层查找（同目录/子树/vault）都没找到该文件名 | 核对文件名，确认 md 在 vault 内 |
| 图片过大（N 字节，上限 …） | 单图超过 8MB | 压缩图片 |
| Excalidraw 嵌入渲染失败（原因） | 源文件缺失 / 格式异常 / Edge 超时 | 按原因处理；重试通常可解决偶发超时 |
| mermaid 块 渲染失败（原因） | mermaid 语法错误等 | 修正语法；失败已回退云端渲染，可能仍可显示 |
| 已内嵌 md 目录外的本地图片 | 安全可见性提示（引用了 md 目录之外的本地图片并已上云） | 属预期行为，知悉即可 |