墨取 · 石墨文档导出助手（非官方）

墨取是一个原创、非官方的 Chrome Manifest V3 扩展，用于把当前账号有权访问的石墨文档导出到本地。它可以按指定文件夹递归下载并保留相对目录结构，适合备份和后续迁移核验。

项目采用 MIT 许可证，永久免费，无遥测、无广告、无支付或收款入口，也没有开发者服务器。所有程序逻辑均随扩展安装在浏览器中；导出时仅与石墨服务和 Chrome 下载能力交互。

墨取与石墨文档及其他扩展作者不存在隶属、授权或合作关系。请只导出你有权访问和处理的内容，并遵守所在组织的制度及石墨服务条款。

功能

• 导出当前打开的石墨文件夹；
• 识别团队空间根目录的 /space/… 地址；
• 粘贴石墨文件夹链接后导出；
• 逐层浏览并选择个人或团队空间中的文件夹；
• 在高级选项中导出当前账号可见的全部空间；
• 递归处理所选文件夹及其子文件夹，不扫描无关目录；
• 保留所选目录下的相对文件夹结构；
• 与其他下载管理扩展同时启用时，仍会重新声明完整子目录路径；
• 检查文件时实时显示已扫描目录、当前已发现目录、文件和跳过数量；
• 扫描分母会随新子目录被发现而增长，不把未知的最终总数伪装成固定值；
• 扫描在后台分步执行，关闭弹窗不会中止；可在固定标签页中持续查看；
• 扫描遇到临时错误时保留检查点，可继续；也可取消后重新选择；
• 下载前显示文件、文件夹、可导出与会跳过项目数量；
• 显示导出进度，支持暂停、继续、取消和失败重试；
• 弹窗关闭后保存任务状态，再次打开可恢复查看；
• 生成 UTF-8 CSV 结果清单，便于核验迁移结果。

安装

本地安装

1. 下载或克隆本仓库。
2. 打开 chrome://extensions。
3. 开启右上角“开发者模式”。
4. 点击“加载已解压的扩展程序”，选择本项目根目录。
5. 固定“墨取”图标，并先在石墨网页中完成登录。

正式上架后，可直接从 Chrome 应用商店安装经过审核的版本。请核对发布者和“非官方”标识，避免安装来历不明的同名扩展。

三步使用

第一次使用或需要逐个按钮说明：本地直接打开 单文件 HTML 图文操作指南；在 GitHub 中也可阅读 Markdown 版。

1. 选择范围：打开目标石墨文件夹、粘贴文件夹链接，或在扩展内浏览选择。
2. 检查文件：观察实时扫描进度；确认识别出的根目录、文件数量、格式和会跳过项目。扫描量较大时，可点击“固定任务页”让它在独立标签页中继续。
3. 开始导出：观察进度；完成后检查下载目录结构、文件能否打开以及 CSV 结果清单。

每次任务都会在 Chrome 默认下载目录下创建一个导出根目录；例如源目录包含 A/B/C 三个文件夹，本地会保留为 导出根目录/A、导出根目录/B、导出根目录/C。若 Chrome 实际保存位置与请求路径不一致，CSV 会记录 Chrome 返回的真实路径，避免误报。

“全部文件”会遍历当前账号可见的个人和团队空间，耗时更长，也更容易触发服务限流，因此放在高级选项中并需要二次确认。

支持格式

石墨类型	默认格式	可选格式
新文档	DOCX	DOCX、Markdown、PDF、JPG
传统文档	DOCX	DOCX、PDF、WPS
表格	XLSX	XLSX
幻灯片	PPTX	PPTX、PDF
思维导图	XMIND	XMIND、JPG
上传到石墨的 DOCX、XLS、PDF、PPT、ZIP 等文件	原文件	原文件

上传文件会按原文件下载；它们不会套用 Markdown 等石墨原生文档导出格式。应用表格、白板和表单暂不自动导出，会在预检和结果清单中标记为“会跳过”，不会静默遗漏。

权限用途

权限	用途
activeTab	用户点击扩展时识别当前打开的石墨文件夹，不读取浏览历史
alarms	Chrome 回收后台进程后安全唤醒下一步扫描或导出，避免长任务静默停住
cookies	仅在用户主动浏览或检查文件时刷新当前 Chrome 已有的石墨登录会话，不保存或显示 Cookie 值
downloads	把导出文件和 CSV 清单保存到浏览器下载目录
storage	在本机保存设置、任务进度和结果，支持弹窗重开后恢复
https://*.shimo.im/*	查询当前账号可访问的目录，并请求石墨生成导出文件

扩展不申请剪贴板读取、浏览历史、通知或所有网站访问权限；粘贴链接由用户在输入框中主动完成。

已知限制

• 导出依赖石墨网页当前使用的接口；石墨更新接口后，扩展可能需要升级。
• 扩展不会绕过登录、访问权限、验证码、频率限制或石墨自身的导出限制。
• 下载文件名冲突时由 Chrome 安全重命名，结果清单用于辅助核验。
• 第一版只负责导出到本地，不会上传到任何云平台。
• 大型目录可能需要较长时间。扫描页中的“当前已发现目录”是动态分母：发现新的子目录时会继续增长，因此进度条可能暂时回退，这不代表扫描重启。
• 程序不设置固定目录层级或文件数量上限；自动化压力测试覆盖 1000 层和 5000 个文件。5000 是便于核验和降低限流风险的分批建议，不是硬限制。实际规模仍受 Chrome 本地任务存储配额、文件名长度及石墨限流影响。
• 扫描和导出检查点都会保存在本机。关闭弹窗后后台仍会分步执行；扫描时可打开固定任务页持续查看。临时扫描错误可从保留的目录队列继续，也可取消后重新选择。
• 导出时可手动暂停，并在当前文件结束后生效。若 Chrome 或后台进程意外中断，重新打开扩展后可继续，失败文件也可单独重试。
• 迁移前应抽样检查格式、附件、公式、评论和复杂排版是否满足后续系统要求。

故障排查

• 提示未登录：打开石墨网页完成登录，再重新检查文件。
• 链接无效：确认链接指向石墨文件夹，而不是单个文档。
• 扫描数字看起来变慢或进度条回退：扫描过程中会继续发现新的子目录，分母随之增长；只要已扫描数量仍在变化，任务就在正常推进。可点击“固定任务页”持续查看。
• 扫描遇到问题：先点击“继续扫描”，会从保留的检查点重试当前目录；若范围选错，可取消并重新选择。
• 团队空间根目录无法识别：请升级到 0.1.4 或更新版本；旧版只识别 /folder/…，0.1.4 起同时识别 /space/…。
• 提示无权限：用当前账号在石墨网页中直接打开该文件夹确认权限。
• 接口可能已更新：安装最新版本，并在仓库中提交不含敏感信息的问题说明。
• 个别文件失败：任务结束后使用“重试失败项目”；仍失败时可先在石墨网页中手工导出该文件。
• 下载未出现：检查 Chrome 下载记录、系统磁盘空间和下载权限设置。

报告问题时不得提交 Cookie、令牌、完整请求头、真实公司文件名、目录结构或文档内容。

本地开发与测试

需要 Node.js 22 或更高版本。项目无运行时依赖、无构建步骤。

npm test
npm run check

真实下载测试必须使用专门的小型测试文件夹，并在开始前核对范围和文件数量；不要直接对公司全量空间执行首次测试。

隐私与安全

请阅读 PRIVACY.md 和 SECURITY.md。任务记录可在扩展界面中清除，也可通过 Chrome 删除本扩展的本地数据。

致谢

感谢既有社区工具提供的问题启发。本项目的代码、设计、文案与素材均为独立实现。

许可证

MIT