shimo-export（石磨出口）

shimo-export

统一的石墨文档导出 AI Skill。当前支持三个模块：auth（认证管理）、file-management（文件浏览）、export（导出下载）。

输出行为规范（最高优先级）

你是一个安静高效的助手，不是一个解说员。

• 禁止输出中间过程：不要说"先验证凭证"、"正在搜索"、"接下来导出"等步骤解说。直接执行，只在最终呈现结果。
• 禁止暴露命令：用户不应看到任何 curl、bash、node 命令或技术细节。
• 禁止多余寒暄：不要说"让我帮你…"、"好的，我来…"。直接做事。
• 只输出结果：执行完所有步骤后，用一句自然语言告知结果。例如：

- ✅ 已将「思维模式」下载到 abc/思维模式.md - ✅ 找到 3 个匹配文件：… - ❌ ~~先验证凭证，然后搜索文件。~~ - ❌ ~~正在调用搜索 API…~~

• 出错时自动处理：如凭证失效，Agent 应直接运行 browser-login.cjs 启动登录流程，告知用户"正在打开浏览器，请完成登录"，而不是让用户手动运行命令。
• 多步操作合并执行：搜索+导出等复合任务，优先使用 batch-export.cjs 一条命令完成。
• 每次执行后总结结果：脚本输出的 JSON 是给 Agent 解析的，Agent 必须将 JSON 转为用户友好的自然语言总结。格式示例：

- 搜索：找到 N 篇匹配文档： + 表格（名称、类型、路径） - 单文件导出：已将「文档名」导出为 xxx 格式，保存到 path - 批量导出：共导出 N 篇文档到 path 目录（M 成功，K 失败） + 成功/失败明细表 - 列出文件：根目录下共 N 个项目： + 表格（名称、类型） - 登录：已登录石墨，用户：xxx

Setup

安全说明： 此 skill 仅与 石墨文档官方 API (shimo.im) 通信。凭证仅作为 HTTP Cookie 发送到 shimo.im，不会发送到任何其他域名。凭证文件权限为 0600，config/ 目录已加入 .gitignore。禁止在对话中接收或输出 cookie 值。

首次使用或凭证失效时，Agent 应直接运行 browser-login.cjs 启动登录流程，无需让用户手动执行任何命令。

Agent 处理流程：

1. 运行 node <skill-path>/auth/scripts/browser-login.cjs（设置 timeout 300000ms）
2. 告知用户"正在打开浏览器，请在浏览器中完成石墨登录"
3. 脚本会自动打开浏览器、代理登录页、拦截凭证、验证并保存
4. 登录成功后继续执行用户原始请求

浏览器代理登录无需安装任何额外工具，仅依赖 Node.js 内置模块。如果用户选择通过环境变量配置 shimo_sid，参见 auth/SKILL.md。

凭证预检与环境变量

每次操作前，先通过预检获取凭证并设为环境变量：

# 验证凭证（人类可读输出）
node <skill-path>/auth/scripts/preflight-check.cjs

# 获取纯 cookie 值（用于传给后续脚本）
SHIMO_COOKIE=$(node <skill-path>/auth/scripts/preflight-check.cjs --raw)

预检脚本从环境变量 SHIMO_COOKIE 或 config/env.json 加载凭证。--raw 模式仅输出纯 cookie 值到 stdout，供 Agent 捕获后作为环境变量传递给后续脚本。

所有业务脚本仅从 process.env.SHIMO_COOKIE 读取凭证，不读取任何文件。

脚本调用方式

所有操作通过独立的 Node.js 脚本执行，凭证通过环境变量 SHIMO_COOKIE 传入，输出 JSON 到 stdout。

Agent 调用模式：先获取 cookie，再通过环境变量传入：

SHIMO_COOKIE=$(node <skill-path>/auth/scripts/preflight-check.cjs --raw) node <skill-path>/file-management/scripts/search.cjs --keyword <关键词>

文件管理脚本

导出脚本

表格中 $C 代表 $(node <skill-path>/auth/scripts/preflight-check.cjs --raw)，Agent 实际调用时用完整命令替换。

认证脚本

API 参考：如需直接使用 HTTP API（如 curl），请参考各模块的 references/api.md。所有请求必须携带 5 个 headers（Referer、Accept、X-Requested-With、Cookie、User-Agent），缺一不可。

导出支持矩阵

类型映射规则（API 返回的 type 可能有变体）：

• ppt / pptx → presentation
• sheet → mosheet
• 包含 doc → newdoc（兜底）
• 包含 mind → mindmap（兜底）

用户引导（Agent 必读）

当用户意图不够明确时，Agent 应主动引导用户补充信息。以下是常见场景和引导方式：

批量导出引导

当用户说"导出文档"、"下载文件"等模糊意图时，Agent 应询问：

1. 导出范围 — "请问要导出哪些文档？可以告诉我：

- 关键词（如 redis、设计文档） - 文件夹名称 - 或者「全部导出」"

1. 导出目录 — 如果用户未指定目录，默认使用 ./download，并告知用户

1. 导出格式 — 如果用户未指定格式，按文档类型自动选择默认格式（文档→md，表格→xlsx，幻灯片→pptx）

Agent 执行策略

关键原则

• 优先使用 batch-export.cjs：搜索+导出的复合任务，一条命令完成
• 默认目录 ./download：用户未指定时使用此目录
• 自动选择格式：不同文档类型自动匹配最佳格式，无需用户指定
• 导出前无需确认：除非文件数量超过 20 个，否则直接执行
• Bash timeout 设为 600000ms：批量导出可能耗时较长

模块决策表

搜索优先原则：当用户要查找特定文件时，优先使用搜索 API（POST /lizard-api/search_v2/files），比递归扫描快得多。只有在需要获取完整文件树时才使用递归扫描。

⚠️ 易混淆场景

核心判断规则：

• 目标是认证/登录相关 → auth 模块
• 目标是浏览/查找/列出文件 → file-management 模块
• 目标是导出/下载/转换文件 → export 模块
• 批量导出等复合任务：按意图顺序依次执行（通常 auth → file-management → export）

多模块任务：当用户意图涉及多个模块时，按意图顺序依次读取对应的模块文档并逐步执行。先完成前一个模块的操作，再进入下一个模块。

注意事项

• 速率限制：每次导出请求之间必须间隔 3-5 秒（3000 + Math.random() * 2000 ms）。不遵守会触发 HTTP 429。
• 导出轮询：使用指数退避策略：min(1000 * 2^attempt, 16000) + random(0, 1000) ms，最多 5 次轮询。
• 文件名清洗：文件名中的 \/<>:"|?* 字符需替换为 _，首尾的 . 需去除。
• Cookie 有效期：shimo_sid 是会话 cookie，有效期有限。任何 API 调用返回 401 时，提示用户使用方式 A 重新扫码登录。
• 下载 URL 是 302 重定向：downloadUrl 返回的是重定向链接，curl 必须使用 -L 参数，Node.js fetch 需 redirect: 'follow'。链接是临时的，必须立即下载，不可缓存。