NeoDB

NeoDB 书影音标注助手 — 通过 API 替代网页/客户端完成所有 NeoDB 操作。支持搜索条目、标记（想看/在看/看过/放弃）、评分、短评、长评、笔记、收藏单、标签管理。触发场景：(1) 用户提到 NeoDB、书影音、标记、想看、看过、在读、读完、评分、评论 (2) 用户要搜索/标注书籍、电影、剧集、音乐...

Security Scan

The skill's behavior mostly matches its stated purpose (interacting with NeoDB) but the package metadata omits required credentials and the included auth script writes sensitive tokens/ client secrets to disk — this mismatch and local persistence warrant caution.

Purpose & Capability

The skill claims to operate NeoDB via its API, which legitimately requires an OAuth token and (optionally) an instance hostname. The SKILL.md explicitly requires NEODB_TOKEN and NEODB_INSTANCE, but the registry metadata declares no required environment variables or primary credential — that inconsistency is unexpected and reduces transparency.

Instruction Scope

SKILL.md provides concrete curl templates and clearly limits operations to NeoDB API endpoints. It instructs storing NEODB_TOKEN (in ~/.claude/settings.json env) and to run the provided scripts/setup-auth.sh. The instructions promise user confirmation before write operations. No instructions request unrelated files, other service credentials, or exfiltration to unexpected endpoints.

Install Mechanism

There is no install spec (instruction-only skill). The only code file is a local bash auth helper; there are no downloads, package installs, or archive extraction steps. This is a low-risk install surface.

Credentials

The SKILL.md legitimately requires NEODB_TOKEN (OAuth access token) and optionally NEODB_INSTANCE. Those are proportional to the stated purpose. However the registry metadata does not declare these required env vars or a primaryEnv, which is an inconsistency. The included script also produces and stores client_id/client_secret and access_token locally — these are sensitive and should be explicitly declared and documented in metadata.

Persistence & Privilege

The setup script writes credentials to a local file (scripts/.credentials.json) and prints the access token; it also advises adding the token to ~/.claude/settings.json. The skill is not marked always:true and does not modify other skills, but local persistence of client_secret and access_token is a real sensitivity (risk of accidental commit or exposure) and should be considered before use.

What to consider before installing

This skill appears to do what it says (call NeoDB APIs), but be cautious: SKILL.md requires an OAuth token (NEODB_TOKEN) and optional NEODB_INSTANCE while the registry metadata does not declare those credentials — an omission that reduces transparency. The included scripts/setup-auth.sh will (1) register an OAuth app on the chosen NeoDB instance, (2) open a browser for you to authorize, and (3) save client_id, client_secret, and the access_token to scripts/.credentials.json and print the token. Before installing or running it: - Review scripts/setup-auth.sh closely (it only talks to your chosen NeoDB instance, but it stores secrets locally). - Do not run the script if you don't trust the instance you select. Prefer specifying the official/neodb.social instance if that's your intent. - Consider creating an OAuth token manually in the instance UI and exporting it to your environment instead of running the script. - If you run the script, move or protect scripts/.credentials.json and add it to .gitignore (the script already suggests this). - Ask the skill author/registry to update the metadata to list NEODB_TOKEN (primaryEnv) and NEODB_INSTANCE so required permissions are explicit. If you need a safer test: run the script in an isolated environment (VM/container) and avoid committing any credential files.

NeoDB 书影音标注助手

通过 NeoDB API 替代网页/客户端完成搜索、标注、评论等全部操作。

前置条件

需要环境变量（~/.claude/settings.json → env）：

• NEODB_TOKEN — OAuth Access Token（必须）
• NEODB_INSTANCE — 实例域名（可选，默认 neodb.social）

首次使用运行鉴权：bash scripts/setup-auth.sh [instance]

API 调用模板

# GET
curl -s -H "Authorization: Bearer $NEODB_TOKEN" \
  "https://${NEODB_INSTANCE:-neodb.social}/api/{endpoint}"

# POST (JSON)
curl -s -X POST -H "Authorization: Bearer $NEODB_TOKEN" \
  -H "Content-Type: application/json" -d '{...}' \
  "https://${NEODB_INSTANCE:-neodb.social}/api/{endpoint}"

所有写入操作执行前必须向用户确认。

核心工作流

搜索 → 标记（最常用）

# 1. 搜索
curl -s "https://${NEODB_INSTANCE:-neodb.social}/api/catalog/search?query={关键词}&category={类型}"
# category: book, movie, tv, movie,tv, music, game, podcast, performance

# 2. 标记
curl -s -X POST -H "Authorization: Bearer $NEODB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shelf_type":"complete","visibility":0,"rating_grade":8,"comment_text":"短评","tags":["标签"],"post_to_fediverse":false}' \
  "https://${NEODB_INSTANCE:-neodb.social}/api/me/shelf/item/{uuid}"

shelf_type: wishlist=想看, progress=在看, complete=看过, dropped=放弃 visibility: 0=公开, 1=仅关注者, 2=私密 rating_grade: 1-10（五星对应: 2/4/6/8/10），0=不评分

从外部链接导入

curl -s "https://${NEODB_INSTANCE:-neodb.social}/api/catalog/fetch?url={豆瓣/IMDB/Goodreads链接}"
# 302=已存在(提取URL中UUID), 202=抓取中(等15秒重试), 422=不支持

浏览书架

curl -s -H "Authorization: Bearer $NEODB_TOKEN" \
  "https://${NEODB_INSTANCE:-neodb.social}/api/me/shelf/{type}?category={category}&page=1"
# type: wishlist, progress, complete, dropped
# category: book, movie, tv, music, game, podcast, performance

写长评

curl -s -X POST -H "Authorization: Bearer $NEODB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"标题","body":"正文(Markdown)","visibility":0,"post_to_fediverse":false}' \
  "https://${NEODB_INSTANCE:-neodb.social}/api/me/review/item/{uuid}"

写笔记

curl -s -X POST -H "Authorization: Bearer $NEODB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"标题","content":"内容","visibility":0,"progress_type":"page","progress_value":"120"}' \
  "https://${NEODB_INSTANCE:-neodb.social}/api/me/note/item/{uuid}/"
# progress_type: page, chapter, timestamp, percentage, null

完整 API 参考

按需查阅，不必全部加载：

• 标记/书架/评论/笔记: references/shelf-and-journal.md
• 收藏单/标签: references/collection-and-tag.md
• 目录/搜索/条目详情: references/catalog.md
• 官方 OpenAPI Spec: references/openapi.json

输出格式

搜索结果：

📖 书名 — 作者
   ⭐ 8.5/10 (120人) | UUID: xxx

标记成功：

✅ 已标记「书名」为 读过 ⭐⭐⭐⭐ (8/10)
   短评：评论内容 | 标签：标签1, 标签2

错误处理

状态码	含义	处理
401	未授权	检查 NEODB_TOKEN
404	未找到	条目不存在
202	抓取中	等 15 秒重试 fetch
429	频率限制	等待重试