# 使用教程

## 1. 启动万能导

普通用户推荐下载发行版安装包，安装后直接打开 `Wandao`。发行版已经内置 Python 运行时和依赖，不需要额外安装 Python。

如果你在本地拉取源码参与开发，可以用下面的方式启动：

```powershell
python -m pip install -r requirements.txt
cd wandao_electron
npm install
npm start
```

旧版 Python 图形界面已废弃。源码启动请统一使用 Tauri 2 桌面端；如果启动失败，请优先检查 Node.js/npm、Rust 1.88.0、Tauri 系统依赖或重新运行启动脚本。

桌面端左侧是工作台入口。先进入“平台中心”，选择平台后再选择导出、导入或查看教程。进入具体操作页后，按界面提示填写链接、登录、读取目录并执行任务。

侧边栏的“教程公告”会从 GitHub 读取 `docs/tutorial-announcements.json`，并展示置顶公告、最新公告、历史公告和教程文档。维护公告时，在 GitHub 修改这个 JSON 的 `items` 列表，再新增或更新对应的 Markdown 文件即可；用户点击“刷新公告”后会读取最新内容。每条内容建议包含 `id`、`type`、`title`、`summary`、`date`、`tags` 和 `path`，其中 `type` 可填写 `announcement` 或 `tutorial`，需要置顶时设置 `pinned: true`。

顶部提供两个常用按钮：

- “夜间模式”：在日间/夜间主题之间切换，工具会记住你的选择。
- “检查更新”：检测 GitHub Releases 是否存在新版本，发现新版后会显示下载提示。

## 2. 第一次登录

每个平台第一次使用都需要保存一次登录凭证：

1. 填写入口 URL。
2. 点击“登录并保存凭证”。
3. 浏览器打开后手动登录。
4. 回到工具窗口点击确认。

凭证文件保存的是 Cookie，不保存账号密码。请不要提交到 Git，也不要分享给他人。

印象笔记比较特殊：它不需要入口 URL。第一次使用时填写账号和密码，点击“登录并同步”，工具会把同步凭证保存到本机同步库里，后续读取目录和导出会使用这个本地同步库，不保存明文密码。

语雀导出默认会本地化正文图片，并尝试下载语雀附件。公开密码库、私有知识库或企业私有域名的附件通常也需要登录态；请先点击“登录并保存凭证”，确认浏览器里能正常访问目标知识库后再导出。若附件很大，可以在语雀导出的“导出选项”里取消“同时下载附件”。

语雀 Markdown 导入使用浏览器登录凭证。进入“平台中心 -> 语雀 -> 导入 Markdown”后，填写目标知识库 URL，点击“登录并保存凭证”，在浏览器中登录并确认能访问目标知识库，再回到工具点击确认。导入前建议先“生成计划”，再“单篇导入测试”，最后批量导入。工具会按本地文件夹创建语雀目录，并上传 Markdown 中的本地图片和附件。

语雀“生成计划”后会在 Markdown 目录生成 `00-语雀导入计划.json`，里面会列出缺失本地图片、远程图片和较大图片明细；导入完成后会生成 `00-语雀导入报告.json`。如果有文档超时或上传失败，可以点击“打开报告”查看具体失败文件，再点击“重试失败”只重试上次失败项。如果图片很大，可以适当调大“图片上传超时秒”和“失败重试次数”。如果同一篇文档图片较多，可以把“资源上传并发”保持为 2 或调到 3；如果遇到语雀限流或网络不稳定，再降回 1。

印象笔记 Markdown 导入使用本机印象笔记同步凭证。进入“平台中心 -> 印象笔记 -> 导入 Markdown”后，第一次使用先填写账号和密码并点击“登录并同步凭证”；已有同步库时可以直接选择 Markdown 目录并导入。

有道云笔记导出不需要填写入口 URL。进入“平台中心 -> 有道云笔记 -> 导出为 Markdown”后，第一次使用点击“登录并保存凭证”，在浏览器里登录并确认能看到笔记列表，再回到工具点击确认。

新电脑上运行时，工具会自动查找 Chrome、Edge 或 Chromium 的常见安装位置，也会检查 PATH。若浏览器安装在非常规位置，可以设置 `WANDAO_BROWSER` 环境变量为浏览器可执行文件路径。

每个导出界面都有“浏览器程序路径”：

- 点击“查找”可以自动扫描本机浏览器。
- 点击“选择”可以手动指定浏览器程序。
- 如果没有找到浏览器，请先安装 Chrome、Edge 或 Chromium，再重新点击“查找”。

## 3. 选择目录

点击“读取目录”后，工具会展示目录树：

- 点击目录或文档可以切换选择。
- “全选”会选择全部文档。
- “全不选”会清空选择。
- “反选”会反转当前选择。

读取目录后，导出按钮只处理已勾选内容。未读取目录时，默认导出全部可识别内容。

## 4. 增量导出

保持“增量导出”勾选，然后点击“开始导出”。

增量模式会识别本地 Markdown 底部的来源标记，跳过已经导出的文档，只补缺失内容。

## 5. 全量导出

取消勾选“增量导出”，然后点击“开始导出”。

全量模式会重新打开并覆盖对应文档，适合远端内容更新后重新同步。

## 6. 进度条、用户日志和任务历史

任务开始后，界面会显示全局进度条：

- 读取目录、登录等无法准确估算的步骤会显示“进行中”。
- 导出和批量导入会显示已处理数量、百分比和部分剩余时间提示。
- 成功完成会显示绿色进度；失败会显示红色进度，并在用户日志里给出更容易理解的错误原因。

用户日志只显示普通用户能直接理解的内容；完整的 Python 输出、错误堆栈和原始返回数据会进入详细日志。遇到问题时，可以点击“提交错误报告给开发者”，工具会复制一份已脱敏的详细报告。

导入或导出任务会进入“任务历史”。你可以：

- 查看最近任务是否完成、失败或被停止。
- 点击“复制报告”生成某一次任务的报告。
- 点击“继续/重试”会优先使用平台声明的失败重试能力；暂不支持失败重试的平台会按历史命令重新执行，适合增量补齐或中断后继续。

如果进度短时间不动，通常是正在等待页面渲染、图片下载、请求延迟或平台响应。可以先看用户日志，必要时点击“停止”。

## 7. 请求延迟

默认参数：

```text
请求延迟秒: 0.8
请求随机浮动秒: 0.4
```

表示每次打开文档或请求正文前等待 `0.8 + 0~0.4` 秒。建议保留默认值或适当调大，不建议调成 0。

知识星球导出默认 URL 深度是 `2`，也就是会导出目录文章本身，并继续进入正文里的下一层知识星球链接。

## 8. 停止任务

导出过程中可以点击“停止当前任务”。工具会在当前文档或图片处理完成后的安全点停止，并保留已经导出的文件和报告。

## 9. 输出目录

默认输出在：

```text
exports/
```

你可以在 GUI 中选择其他目录。建议不要把导出的内容提交到公开仓库。

## 10. 印象笔记导出

1. 进入“平台中心”，选择“印象笔记”。
2. 点击“导出为 Markdown”。
3. 填写印象笔记账号和密码。
4. 点击“登录并同步”，等待工具把笔记本和笔记同步到本地。
5. 点击“读取目录”，选择要导出的笔记本或笔记。
6. 点击“开始导出”，生成 Markdown 和本地附件。

印象笔记导出会先通过同步接口生成本地同步库，再转成 Markdown。这样比网页复制更稳定，也方便按笔记本层级选择范围。

## 11. 印象笔记 Markdown 导入

1. 进入“平台中心”，选择“印象笔记”。
2. 点击“导入 Markdown”。
3. 第一次使用先填写印象笔记账号和密码，点击“登录并同步凭证”。如果已经用“印象笔记导出”登录同步过，可以跳过这一步。
4. 选择本地 Markdown 目录。
5. 填写默认目标笔记本，默认是“万能导导入”。
6. 如果希望保留本地目录层级，勾选“按本地目录创建笔记本组/笔记本”。
7. 点击“扫描目录”，确认本地 Markdown 数量。
8. 点击“单篇导入测试”，先确认正文、图片和附件效果。
9. 点击“批量导入”。

目录映射规则：

- 不勾选目录映射时，所有 Markdown 会导入到默认目标笔记本。
- 勾选目录映射时，一级目录会作为笔记本组，后续目录会作为笔记本名。
- Markdown 中的本地图片和普通附件会作为印象笔记 Resource 上传。

当前导入器会优先保留标题、段落、列表、引用、代码块、链接、本地图片和附件。复杂表格、折叠块、平台私有组件可能会被简化。

## 12. 飞书 Markdown 导入完整流程

飞书导入比导出复杂一些，因为它需要先配置飞书开放平台应用。第一次使用建议按下面顺序操作：

1. 进入“平台中心”，选择“飞书”。
2. 点击“导入 Markdown”。
3. 在“目标飞书 Wiki URL”输入要导入到的 Wiki 页面链接。
4. 在“Markdown 目录”选择本地 Markdown 文件夹；如果只想先测一篇，可以在“单篇测试文件”里选择一个 `.md`。
5. 点击“打开飞书开放平台”，创建企业自建应用。
6. 在飞书开放平台进入应用的“凭证与基础信息”，复制 `App ID` 和 `App Secret`，填回万能导后点击“保存 API 配置”。
7. 点击“初始化开放平台权限”，按页面提示开通 `drive:drive`、`drive:file:upload`、`docs:permission.member:create`、`docs:document:import`、`docx:document`、`docx:document:write_only`、`wiki:wiki`，然后发布应用新版本。
8. 点击“检查应用身份”。如果日志提示没有启用机器人，就在打开的机器人页面启用机器人能力，并再次发布应用新版本。
9. 点击“授权目标 Wiki 文档应用”。如果自动授权没有完成，请打开目标 Wiki 页面，在右上角选择“... -> 更多 -> 添加文档应用”，搜索当前企业自建应用名称，并设置为可编辑。
10. 点击“登录并保存凭证”。浏览器打开后登录飞书，确认能看到目标 Wiki 页面，再回到万能导点击“我已完成登录，保存凭证”。
11. 点击“探测目标 Wiki”，让工具识别 `spaceId` 和目标父页面。
12. 点击“生成计划”，先确认将要导入哪些本地 Markdown 文件。
13. 点击“单篇导入测试”，确认标题、正文、图片和层级正常。
14. 点击“批量导入”，正式把本地 Markdown 按文件夹层级导入飞书 Wiki。

常见错误：

- `99991672`：通常是开放平台 API 权限没开，或开通权限后没有发布新版本。
- `131006` / `no destination parent node permission`：通常是目标 Wiki 父页面没有把当前企业自建应用加入“文档应用”列表，按第 8 步处理。
- 图片没有显示：先确认本地 Markdown 图片路径真实存在，再勾选“修复本地图片”后重试。

## 13. 有道云笔记导出

1. 进入“平台中心”，选择“有道云笔记”。
2. 点击“导出为 Markdown”。
3. 第一次使用点击“登录并保存凭证”。
4. 浏览器打开后登录有道云笔记，确认能看到笔记列表。
5. 回到万能导，点击“我已完成登录，保存凭证”。
6. 点击“读取目录”，选择要导出的目录或笔记。
7. 点击“开始导出”，生成 Markdown、本地图片和附件。

有道云笔记导出会复用浏览器登录态，不需要开发者 Token。Markdown 原文会直接保存；有道 `.note`、剪藏、富文本等格式会尽量转换为 Markdown。遇到普通附件时会原样下载到本地。

## 14. 为知笔记导出

1. 进入“平台中心”，选择“为知笔记”。
2. 点击“导出为 Markdown”。
3. 第一次使用点击“登录并保存凭证”。
4. 浏览器打开后登录网页版为知笔记，确认能看到目标目录。
5. 回到万能导，点击“我已完成登录，保存凭证”。
6. 点击“读取目录”，选择要导出的文件夹或笔记。
7. 点击“开始导出”，生成 Markdown、本地图片和附件。

为知笔记导出会尽量保留网页版目录结构、正文图片和普通附件。遇到平台特殊组件时，工具会尽量转换为 Markdown 可读内容。

## 15. OneNote 导出

1. 进入“平台中心”，选择“OneNote”。
2. 点击“导出为 Markdown”。
3. 确认本机安装的是 Windows 桌面版 OneNote，并且目标笔记本可以在本机打开。
4. 点击“读取本地笔记本”，选择要导出的笔记本、分区或页面。
5. 点击“开始导出”，生成 Markdown、本地图片和附件。

OneNote 导出会读取本机笔记本结构，尽量保留“笔记本 / 分区 / 页面”的目录层级。该能力主要面向 Windows 桌面版 OneNote，macOS 端暂不作为稳定路径。

## 16. ima 说明

ima 当前第一版聚焦“知识库导入导出”，不单独做 ima 笔记导入导出。

- 导出时：可以读取 ima 知识库已有的多层文件夹，并按本地目录保存。
- 导入时：可以选择知识库根目录或已有文件夹上传。
- 限制：ima OpenAPI 暂未看到创建知识库文件夹接口，所以暂不能自动把本地多层目录完整重建到 ima。
- 处理配图：默认不会把 Markdown 引用到的本地图片和附件重复作为独立文件上传，如需单独上传可在高级选项开启。

## 17. 配合 AI 学习代码项目

万能导导出的 Markdown 文档可以和源码项目放在一起，让 AI 同时阅读“教学文档 + 真实代码”。

推荐做法：

1. 用万能导导出你有权限访问的教学文档。
2. 把导出的目录复制到源码项目中，例如：

```text
your-project/
  src/
  docs/
  exported-knowledge/
    00-知识库入口.md
    01-项目介绍.md
    ...
```

3. 用 AI 工具打开整个 `your-project/` 目录。
4. 把 `prompts/项目学习导师提示词.md` 里的提示词发给 AI。
5. 让 AI 按“先读教学文档、再读源码、最后结合业务流程讲解”的方式带你学习。

这种用法适合学习带有源码和配套教学文档的项目，可以减少自己在文档、代码、业务流程之间来回切换的成本。