Skill: navyum/shimo-export (version 1.0.3)

--- name: shimo-export description: | 石墨文档导出 AI Skill — 通过 AI Agent 与石墨文档 (shimo.im) API 交互， 实现自动登录、文件列表浏览、团队空间扫描、批量导出（支持 Markdown、PDF、Word、Excel、PPT、XMind、图片等格式）。 当用户提到石墨文档、导出文件、下载文档、批量导出、团队空间、文件列表时，使用此 skill。 即使用户没有明确说"石墨"，只要意图涉及从 shimo.im 导出或浏览文档，也应触发此 skill。 Shimo Document Export AI Skill — Enables AI agents to interact with shimo.im API for automated login, file browsing, team space scanning, and batch export in multiple formats (md, pdf, docx, xlsx, pptx, xmind, jpg). homepage: https://github.com/Navyum/chrome-extension-shimo-export metadata: openclaw: emoji: '📄' requires: { env: ['SHIMO_COOKIE'] } primaryEnv: 'SHIMO_COOKIE' security: credentials_usage: | This skill uses a shimo_sid session cookie for authentication against shimo.im APIs. The cookie is obtained via a local reverse proxy (localhost:18927) that intercepts the Set-Cookie header during browser login — no external dependencies required. Alternatively, users can set the SHIMO_COOKIE environment variable directly. Credentials are ONLY sent to shimo.im as HTTP Cookie headers. Credentials are stored in config/env.json with file permission 0600. The config/ directory is .gitignore'd to prevent accidental commits. NEVER accept, log, display, or transmit the full cookie value in conversation context. allowed_domains: - shimo.im --- # 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`。 ## 凭证预检与环境变量 每次操作前，先通过预检获取凭证并设为环境变量： ```bash # 验证凭证（人类可读输出） 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，再通过环境变量传入： ```bash SHIMO_COOKIE=$(node <skill-path>/auth/scripts/preflight-check.cjs --raw) node <skill-path>/file-management/scripts/search.cjs --keyword <关键词> ``` ### 文件管理脚本 | 脚本 | 用法 | 功能 | |------|------|------| | `search.cjs` | `SHIMO_COOKIE=$C node <skill-path>/file-management/scripts/search.cjs --keyword <关键词> [--size N] [--type TYPE] [--full-text]` | 搜索文件 | | `list-files.cjs` | `SHIMO_COOKIE=$C node <skill-path>/file-management/scripts/list-files.cjs [folder-guid]` | 列出文件/文件夹 | | `list-spaces.cjs` | `SHIMO_COOKIE=$C node <skill-path>/file-management/scripts/list-spaces.cjs` | 获取团队空间 | ### 导出脚本 | 脚本 | 用法 | 功能 | |------|------|------| | `batch-export.cjs` | `SHIMO_COOKIE=$C node <skill-path>/export/scripts/batch-export.cjs --keyword <关键词> --output <目录> [--format md]` | **一键批量导出** | | `batch-export.cjs` | `SHIMO_COOKIE=$C node <skill-path>/export/scripts/batch-export.cjs --folder <guid> --output <目录>` | 导出文件夹下所有文件 | | `batch-export.cjs` | `SHIMO_COOKIE=$C node <skill-path>/export/scripts/batch-export.cjs --all --output <目录>` | 导出根目录所有文件 | | `export-helper.cjs` | `SHIMO_COOKIE=$C node <skill-path>/export/scripts/export-helper.cjs <fileGuid> <format> [outputDir] [--name "名称"]` | 导出单个文件 | > 表格中 `$C` 代表 `$(node <skill-path>/auth/scripts/preflight-check.cjs --raw)`，Agent 实际调用时用完整命令替换。 ### 认证脚本 | 脚本 | 用法 | 功能 | |------|------|------| | `browser-login.cjs` | `node <skill-path>/auth/scripts/browser-login.cjs` | 启动本地反向代理引导浏览器登录（推荐） | | `preflight-check.cjs` | `node <skill-path>/auth/scripts/preflight-check.cjs` | 验证凭证有效性 | | `preflight-check.cjs --raw` | `node <skill-path>/auth/scripts/preflight-check.cjs --raw` | 输出纯 cookie 值（供环境变量传递） | > **API 参考**：如需直接使用 HTTP API（如 curl），请参考各模块的 `references/api.md`。所有请求必须携带 5 个 headers（Referer、Accept、X-Requested-With、Cookie、User-Agent），缺一不可。 ## 导出支持矩阵 | 文档类型 | API type 值 | 支持格式 | 默认格式 | |---------|------------|---------|---------| | 新版文档 | `newdoc` | md, jpg, docx, pdf | md | | 传统文档 | `modoc` | docx, wps, pdf | docx | | 表格 | `mosheet` | xlsx | xlsx | | 幻灯片 | `presentation` | pptx, pdf | pptx | | 思维导图 | `mindmap` | xmind, jpg | xmind | | 表单/白板/画板 | `table`, `board`, `form` | **不支持导出** | — | **类型映射规则**（API 返回的 type 可能有变体）： - `ppt` / `pptx` → `presentation` - `sheet` → `mosheet` - 包含 `doc` → `newdoc`（兜底） - 包含 `mind` → `mindmap`（兜底） ## 用户引导（Agent 必读） 当用户意图不够明确时，Agent 应主动引导用户补充信息。以下是常见场景和引导方式： ### 批量导出引导 当用户说"导出文档"、"下载文件"等模糊意图时，Agent 应询问： 1. **导出范围** — "请问要导出哪些文档？可以告诉我： - 关键词（如 redis、设计文档） - 文件夹名称 - 或者「全部导出」" 2. **导出目录** — 如果用户未指定目录，默认使用 `./download`，并告知用户 3. **导出格式** — 如果用户未指定格式，按文档类型自动选择默认格式（文档→md，表格→xlsx，幻灯片→pptx） ### Agent 执行策略 | 用户说的 | Agent 行为 | |---------|-----------| | "导出 redis 相关文档" | 直接运行 `batch-export.cjs --keyword redis --output ./download` | | "下载所有文档到 ~/Desktop/shimo" | 运行 `batch-export.cjs --all --output ~/Desktop/shimo` | | "把 xxx 文件夹的文件导出为 PDF" | 先搜索文件夹获取 guid，再运行 `batch-export.cjs --folder <guid> --output ./download --format pdf` | | "导出文档" （模糊） | 询问导出范围和目录 | | "查找 xxx 文档" | 用 `search.cjs` 搜索，展示结果，等待用户指示是否导出 | ### 关键原则 - **优先使用 `batch-export.cjs`**：搜索+导出的复合任务，一条命令完成 - **默认目录 `./download`**：用户未指定时使用此目录 - **自动选择格式**：不同文档类型自动匹配最佳格式，无需用户指定 - **导出前无需确认**：除非文件数量超过 20 个，否则直接执行 - **Bash timeout 设为 600000ms**：批量导出可能耗时较长 ## 模块决策表 | 用户意图 | 模块 | 读取 | |---------|------|------| | 登录、扫码、认证、cookie 过期、重新登录 | auth | `auth/SKILL.md` | | **搜索文件、查找文档**、列出文件、浏览文件夹、查看团队空间、扫描所有文件 | file-management | `file-management/SKILL.md` | | 导出文件、下载文档、批量导出、转换格式、查看导出进度 | export | `export/SKILL.md` | > **搜索优先原则**：当用户要查找特定文件时，优先使用搜索 API（`POST /lizard-api/search_v2/files`），比递归扫描快得多。只有在需要获取完整文件树时才使用递归扫描。 ### ⚠️ 易混淆场景 | 用户说的 | 实际意图 | 正确路由 | |---------|---------|---------| | "帮我导出石墨文档" | 需要知道范围 | 询问关键词/文件夹，然后 `batch-export.cjs` 一键完成 | | "下载我所有的文件" | 批量导出 | `batch-export.cjs --all --output ./download` | | "登录失败" / "token 过期" | 凭证问题 | **auth** — 重新扫码登录 | | "导出为 PDF" | 单文件导出（需要知道文件 ID） | 先问用户哪个文件，或用 **file-management** 查找 → **export** | | "查看我有哪些文件" | 仅浏览，不导出 | **file-management** | | "把表格导出为 markdown" | 格式不支持（mosheet 只支持 xlsx） | 告知用户不支持，建议 xlsx | **核心判断规则**： - 目标是**认证/登录**相关 → 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'`。链接是临时的，必须立即下载，不可缓存。


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (HIGH)