Notes Export API

What it does

When your agent uses it

• Tasks that involve Markdown

Example prompts

• “/notes-export-api”

Requirements

• Node.js
• A Bash shell
• Docker
• A credential in NOTES_API_TOKEN

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

1. 1优先使用 NOTES_API_TOKEN。Token 缺失时，用 NOTES_API_USERNAME 和
2. 2先执行 list 或 folders，取得真实的便签 ID 和文件夹 ID；不要猜测 ID。
3. 3对单张便签执行 get、update、delete、restore、classify、star、
4. 4新增或更新便签时优先使用 --markdown-file，避免多行 Markdown 的命令行转义
5. 5普通 delete 只移入回收站。仅在调用方明确要求不可恢复地删除时，才对回收站
6. 6读取脚本输出的 JSON；失败时把标准错误中的 error 原样反馈。
7. 7遇到同时写入冲突时允许脚本自动重读并重试，不要盲目覆盖整个工作区。

What it can do on your machine

Read from SKILL.md and the folder at commit d07a926. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 2 files in scripts/ (Shell and JavaScript), which the agent can run.

  Shell commands in SKILL.md call:

  • node

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • NOTES_API_PASSWORD
  • NOTES_API_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Notes Export API loads about 1.1k tokens when it runs, and up to ~2.1k if it reads all its reference files. Until then it costs about 85 tokens; SKILL.md has 197 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~85

When it runs · the whole SKILL.md, loaded when a task matches

~1.1k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:3

  rkdown 转便签图片或批量长图导出时使用。服务地址没有默认值，调用方必须通过 .env 或命令行明确提供。

• NoteMentions a .env fileSKILL.md:15

  到版本库的 `.env`：

• NoteMentions a .env fileSKILL.md:23

  向 `/api/auth/skill-token` 申请 Token，原子更新 `.env`，并移除用户名和

• NoteMentions a .env fileSKILL.md:29

  单人部署时，把项目根目录 `.env` 中 `SUPERADMIN` 和 `SUPERADMINPASSWORD` 的实际值

• NoteMentions a .env fileSKILL.md:43

  没有 `.env` 时，给命令显式传入同名参数：

• NoteMentions a .env fileSKILL.md:57

  如果 `.env` 和命令行都没有服务地址，停止执行并请调用方补充；不得自动探测本地

• NoteMentions a .env fileSKILL.md:166

  - 命令行参数覆盖 `.env`；显式 `--env-file` 优先于调用进程和 Skill 目录 `.env`。

• NoteMentions a .env fileSKILL.md:169

  后把 Token 写回 `.env`、移除账号密码。

• NoteMentions a .env fileSKILL.md:172

  不要输出、记录或提交密码。优先通过环境变量或已被 Git 忽略的 `.env` 提供

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from zhaoolee/notes at commit d07a926, republished under its Apache-2.0 licence (© zhaoolee). 197 words, ~1,145 tokens.

name

notes-export-api

description

通过 Token 或首次使用的用户名与密码连接调用方明确配置的锤子便签服务，管理当前账号的云端工作区并导出内容。支持便签列表与全文查询、新增、更新 Markdown、软删除、回收站恢复、显式永久删除、文件夹分类、星标、置顶、生成可粘贴到微信公众号的富文本 HTML，以及把 Markdown 或本地 .md 文件导出为带图的锤子便签长图 PNG；导出支持 default 暖白纸感、smartisan-dark 暗黑主题和自定义底部文案。用户提到锤子便签、用 AI 增删改查便签、便签查询或自动维护、分类、收藏、置顶、公众号复制格式、Markdown 转便签图片或批量长图导出时使用。服务地址没有默认值，调用方必须通过 .env 或命令行明确提供。

NOTES_API_BASE_URL=http://127.0.0.1:18080
NOTES_API_TOKEN=notes_sk_v1.xxx

node scripts/notes_api.mjs list --env-file /abs/path/notes-api.env
scripts/export_note.sh \
  --env-file /abs/path/notes-api.env \
  --markdown '正文' \
  --output /abs/path/note.png

node scripts/notes_api.mjs list \
  --base-url https://notes.example.com \
  --username your-account \
  --password your-password

scripts/export_note.sh \
  --base-url https://notes.example.com \
  --markdown '正文' \
  --output /abs/path/note.png

export NOTES_API_BASE_URL=http://127.0.0.1:18080
export NOTES_API_TOKEN=notes_sk_v1.xxx

node scripts/notes_api.mjs list

node scripts/notes_api.mjs list --category trash

node scripts/notes_api.mjs get --note-id NOTE_ID

node scripts/notes_api.mjs add \
  --markdown-file /abs/path/note.md

node scripts/notes_api.mjs update \
  --note-id NOTE_ID \
  --markdown-file /abs/path/note.md

node scripts/notes_api.mjs delete --note-id NOTE_ID

node scripts/notes_api.mjs restore --note-id NOTE_ID

node scripts/notes_api.mjs delete \
  --note-id NOTE_ID \
  --permanent

node scripts/notes_api.mjs folders

node scripts/notes_api.mjs folder-create --name 工作

node scripts/notes_api.mjs classify \
  --note-id NOTE_ID \
  --folder 工作

node scripts/notes_api.mjs star \
  --note-id NOTE_ID \
  --state on

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

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/note-dark.png

© zhaoolee, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts, references) in skills/notes-export-api of zhaoolee/notes.

• SKILL.md
• .env.example
• agents/openai.yaml
• references/workspace-api.md
• scripts/export_note.sh
• scripts/notes_api.mjs
• skill-card.md

Open the folder on GitHubat commit d07a926