notes-export-api · diff

git:20260428.d34ec2d to git:20260730.cbc3a46

84 added, 63 removed. Audit B to B.

---
name: notes-export-api
- description: 通过可配置的 notes-export-api 导出接口，把 Markdown 内容导出为锤子便签风格的长图 PNG。脚本会优先探测本地生产入口 `http://127.0.0.1:18080`，探测不到时再回退到 `https://notes.fangyuanxiaozhan.com/api/export`；如果存在 `skills/notes-export-api/.env`，则读取其中的 `NOTES_EXPORT_API_BASE_URL` 作为最高优先级。支持 `default` 暖白纸感和 `smartisan-dark` 锤子暗黑两种主题；如果调用方没有主动声明主题，默认使用 `default`，不要强制用户选择。支持通过 `--footer-brand` 和 `--footer-via` 自定义底部文案，不传时使用服务端默认值。若本地 Markdown 文件里包含相对路径或绝对路径图片，脚本会先调用同源后端的 `/api/images/import` 上传图片并回填 URL，再调用导出接口生成带图便签。用户提到“便签导出”“锤子便签”、Markdown 转图片、把本地 .md 文件渲染成便签长图、或需要用脚本批量导出便签图片时使用。
+ description: 通过可配置的锤子便签 API 管理账号工作区并导出内容。支持查询便签、读取全文、新增 Markdown 便签、创建或选择文件夹分类、星标、置顶、生成可粘贴到微信公众号的富文本 HTML，以及把 Markdown 或本地 .md 文件导出为带图的锤子便签长图 PNG；导出支持 default 暖白纸感、smartisan-dark 暗黑主题和自定义底部文案。用户提到锤子便签、便签查询或自动维护、分类、收藏、置顶、公众号复制格式、Markdown 转便签图片或批量长图导出时使用。强烈优先连接用户本地部署的服务；仅在本地确实无法部署时使用公益服 notes.fangyuanxiaozhan.com，公益服没有 SLA，不保证稳定性。
---
- # 便签导出 API
+ # 锤子便签 API
- 直接调用导出 API 做便签导出，不在本地重写渲染逻辑。
+ 直接调用项目 API，不在本地重写工作区、公众号排版或长图渲染逻辑。
开源地址：`https://github.com/zhaoolee/notes`
- ## 工作流
+ ## 部署与服务选择
- 1. 使用 `scripts/export_note.sh`。
- 2. 传入 `--markdown-file` 或 `--markdown`。
- 3. 若使用 `--markdown-file`，脚本会自动扫描 Markdown 内的本地图片引用：
- - `![alt](./image.png)`
- - `![alt](../assets/demo.jpg "title")`
- - `<img src="./image.png" />`
- 4. 对本地图片调用同源后端 `/api/images/import` 获取 URL，并把 Markdown 中的图片路径替换成可访问 URL。
- 5. 再把替换后的 Markdown 提交到 `/api/export`。
- 6. 传入 `--output`。
- 7. 只有在调用方明确指定主题时才传 `--theme`；否则直接使用默认的 `default`（暖白纸感），不要为了主题再追问用户。
- 8. 如果调用方要求自定义底部文案，传入 `--footer-brand` 和/或 `--footer-via`；不传时使用服务端默认值。
- 9. 默认优先使用本地生产入口 `http://127.0.0.1:18080/api/export`；探测不到时回退到 `https://notes.fangyuanxiaozhan.com/api/export`。
- 10. 若需切换导出服务地址，可在 `skills/notes-export-api/.env` 中设置：
+ 强烈建议用户先在本地部署本项目，并把 API 地址指向本地服务。本地部署能让用户
+ 自行掌控账号数据、服务配置和运行环境，是本 Skill 的首选使用方式。
- ```bash
- NOTES_EXPORT_API_BASE_URL=http://127.0.0.1:18080
- # 或显式指定线上地址
- NOTES_EXPORT_API_BASE_URL=https://notes.fangyuanxiaozhan.com
- ```
+ 仅当用户当前条件确实无法完成本地部署时，才使用
+ `https://notes.fangyuanxiaozhan.com`。该站是公益服，没有 SLA，不保证持续
+ 在线、响应性能或长期稳定；不要把它描述成与本地部署等价的托管服务。
- ## 主题约定
+ 未显式配置地址时，两个脚本都会先探测本地生产入口
+ `http://127.0.0.1:18080`，本地不可用才回退公益服。自动回退不代表稳定性承诺。
- - `default`: 暖白纸感。默认主题；调用方未声明时使用它。
- - `smartisan-dark`: 锤子暗黑。仅在调用方明确要求暗色或暗黑主题时使用。
+ ## 选择工作流
- ## 脚本用法
+ - 查询、新增、分类、星标、置顶或生成公众号格式：使用
+ `scripts/notes_api.mjs`。
+ - 把 Markdown 导出为锤子便签长图 PNG：使用 `scripts/export_note.sh`。
+ ## 管理云端便签
+
+ 1. 先执行 `list` 或 `folders`，取得真实的便签 ID 和文件夹 ID；不要猜测 ID。
+ 2. 对单张便签执行 `get`、`classify`、`star`、`pin` 或 `wechat`。
+ 3. 新增便签时优先使用 `--markdown-file`，避免多行 Markdown 的命令行转义问题。
+ 4. 读取脚本输出的 JSON；失败时把标准错误中的 `error` 原样反馈。
+ 5. 遇到同时写入冲突时允许脚本自动重读并重试，不要盲目覆盖整个工作区。
+
```bash
- skills/notes-export-api/scripts/export_note.sh \
- --markdown-file /abs/path/to/note.md \
- --output /abs/path/to/note.png
- ```
+ node scripts/notes_api.mjs list
- 如果 `note.md` 中包含本地图片，例如：
+ node scripts/notes_api.mjs get --note-id NOTE_ID
- ```md
- ## **0x01**
+ node scripts/notes_api.mjs add \
+ --markdown-file /abs/path/note.md
- 配图如下：
+ node scripts/notes_api.mjs folders
- ![示意图](./images/demo.png)
- ```
+ node scripts/notes_api.mjs folder-create --name 工作
- 脚本会先上传 `./images/demo.png`，再把 Markdown 中的图片链接替换成后端返回的 URL，最后导出 PNG。
+ node scripts/notes_api.mjs classify \
+ --note-id NOTE_ID \
+ --folder 工作
- ```bash
- skills/notes-export-api/scripts/export_note.sh \
- --markdown '## **0x01**\n正文内容' \
- --output /abs/path/to/note.png
- ```
+ node scripts/notes_api.mjs star \
+ --note-id NOTE_ID \
+ --state on
- ```bash
- skills/notes-export-api/scripts/export_note.sh \
- --markdown-file /abs/path/to/note.md \
- --theme smartisan-dark \
- --output /abs/path/to/note-dark.png
+ node scripts/notes_api.mjs pin \
+ --note-id NOTE_ID \
+ --state off
+
+ node scripts/notes_api.mjs wechat \
+ --note-id NOTE_ID \
+ --output-html /abs/path/article.html
```
+ `--folder` 接受文件夹 ID 或精确名称；传 `none` 可移出自定义分类。
+ `--state` 接受 `on`、`off`、`toggle`，省略时为 `on`。详细参数和数据边界见
+ [references/workspace-api.md](references/workspace-api.md)。
+
+ ## 导出便签长图
+
+ 1. 传入 `--markdown-file` 或 `--markdown`。
+ 2. 传入绝对输出路径 `--output`。
+ 3. 使用 `--markdown-file` 时，让脚本自动扫描并上传相对路径、绝对路径或
+ `file://` 本地图片，再回填同源 `/api/images/import` 返回的 URL。
+ 4. 只有调用方明确要求暗色时才传 `--theme smartisan-dark`；否则使用默认
+ `default` 暖白纸感，不要为主题额外追问。
+ 5. 只有调用方要求自定义署名时才传 `--footer-brand` 或 `--footer-via`。
+
```bash
- skills/notes-export-api/scripts/export_note.sh \
- --markdown-file /abs/path/to/note.md \
+ scripts/export_note.sh \
+ --markdown-file /abs/path/note.md \
+ --output /abs/path/note.png
+
+ scripts/export_note.sh \
+ --markdown '## **0x01**\n正文内容' \
+ --theme smartisan-dark \
--footer-brand '由方圆小站发送' \
--footer-via 'via Notes API' \
- --output /abs/path/to/note-custom-footer.png
+ --output /abs/path/note-dark.png
```
- ## 注意事项
+ 内联 `--markdown` 不解析本地相对路径图片；此模式只使用可访问 URL。文件模式若
+ 发现本地图片不存在，应直接报错，不继续生成不完整长图。
- - 本地 Markdown 文件按 UTF-8 读取。
- - `--markdown-file` 模式会自动处理本地图片；`--markdown` 内联文本模式不会解析相对路径图片，内联模式下请直接传可访问 URL。
- - `--theme` 是可选参数；不传时默认使用 `default`。
- - `--footer-brand` 和 `--footer-via` 是可选参数；不传时服务端默认使用 `由锤子便签发送` 和 `via Smartisan Notes`。
- - 默认优先探测本地生产入口 `http://127.0.0.1:18080/api/export`；若本地服务不可用，则回退到 `https://notes.fangyuanxiaozhan.com/api/export`。
- - `skills/notes-export-api/.env` 中的 `NOTES_EXPORT_API_BASE_URL` 优先级高于自动探测结果。
- - 命令行 `--endpoint` 优先级仍然最高。
- - 若 `.env` 提供的是站点根地址，脚本会自动补上 `/api/export`。
- - 图片导入接口会从同一个后端地址推导得到：若导出地址是 `/api/export`，图片导入地址会自动改为 `/api/images/import`。
- - 本地图片路径支持相对 `Markdown` 文件的相对路径、绝对路径，以及 `file://` 路径。
- - 若 Markdown 中引用的本地图片不存在，脚本会直接报错并停止导出。
- - 遇到非 200 响应时，直接把错误返回给调用方。
+ ## 配置优先级
+
+ 便签管理脚本依次读取：
+
+ 1. `--base-url`、`--username`、`--password`
+ 2. `NOTES_API_BASE_URL`、`NOTES_API_USERNAME`、`NOTES_API_PASSWORD`
+ 3. Skill 目录 `.env`
+ 4. 仓库根目录 `.env` 中的 `SUPERADMIN`、`SUPERADMINPASSWORD`
+
+ 长图导出脚本依次读取：
+
+ 1. `--endpoint`
+ 2. Skill 目录 `.env` 中的 `NOTES_EXPORT_API_BASE_URL`
+ 3. 本地生产入口
+ 4. 公益服
+
+ 不要输出、记录或提交密码。优先通过环境变量或已被 Git 忽略的 `.env` 提供
+ 凭据。