Skills

Skills 是一套为 AI 助手（如 Claude）准备的「技能包」。装好之后，你可以用一句话让 AI 帮你搜索笔记、新建笔记、整理标签、管理待办——它会在背后调用 Dinox CLI（dino）替你完成。

准备工作

使用 Skills 前，先装好并登录 Dinox CLI。推荐使用 Node.js 24 LTS；CLI 支持 Node.js 20.18.1+、22、23、24、25，不支持 Node.js 21 或 26+。

第一步，全局安装 CLI：

npm install -g @dinoxx/dinox-cli

第二步，登录你的账号（在自己的终端里运行）：

read -rs DINOX_TOKEN
printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
unset DINOX_TOKEN

安装 Skills

一行命令全局安装：

npx skills add ryzencool/dinox-cli-skills -g

装好后重启你的 AI 助手即可生效。

开始使用

有两种方式，挑顺手的用。

方式一：直接说人话

把它当成懂你笔记的助手，自然提问就行：

帮我搜索最近一周的 AI 笔记
创建一条笔记，标题是「今日复盘」
把这条笔记加到 Inbox 并打星
列出我所有的标签
帮我建一个待办：补交报销单、整理发票

方式二：用斜杠命令

想更精确地指定操作，可以用 / 命令：

/dino-note 搜索最近 7 天的 AI 笔记
/dino-note 创建一条标题为「今日笔记」的笔记
/dino-manage-todo 创建待办：联系供应商
/dino-manage-tags reading/tech
/dino-sync
dino doctor --format json

能做什么

CLI 行为说明

• 读类命令默认使用本地 PowerSync 缓存；需要强一致新鲜度时，Skills 会让 CLI 先执行 dino sync --strict --sync-timeout 600000 --format json，或在读命令上添加 --require-sync。严格模式要求 PowerSync 保持连接、取得晚于本次命令启动时间的新 checkpoint、数据流进入 idle，且没有下载错误。
• 笔记和待办写命令会返回 Write Receipt：durability、upload_queue_remaining、version、content_hash、changed 和 stale。默认可以把 durability: local 视为本地数据库已写入；如果必须等云端上传队列清空，Skills 会加 --durability uploaded，失败时按 UPLOAD_PENDING / suggested_action 处理。
• dino note patch 的 readToken 是短期凭证（当前有效期为 30 分钟，以 readTokenExpiresAt 为准），并绑定生成它时当前账号对应的本地 PowerSync 数据库作用域，不能在切换账号或本地数据库后复用。token 只能使用一次，会在真实 patch 尝试写库前原子消费；任何失败后都必须重新执行 dino note content-read <id>。这样不会在数据库已提交后因 token 文件清理失败而误报整次写入失败。
• dino doctor --format json 会返回认证、同步、上传队列、笔记 FTS 索引对账、daemon 版本 / 账号 / token 指纹 / runtime config 匹配和本地数据库完整性状态；dino doctor --fix --format json 会尝试清空上传队列、重建本地笔记索引并重启 stale daemon。CLI 会先释放数据库 owner lease 再重启 daemon；失败的修复会保持 healthy: false，不会被标记为已修复。
• 结构化错误会在顶层返回 code、recoverable、exit_code 和 suggested_action.command。脚本可以按退出码分支：2 参数错误、3 未登录、4 数据过期 / 上传未完成、5 前置条件或资源缺失。
• dino note search、dino todo search、dino graph backlinks/outlinks/related/stats 在默认在线模式下会使用 daemon-owned DB runtime。daemon 通过用户私有 Unix domain socket 通信（Windows 使用命名管道），并会在 CLI 版本、登录账号、token 指纹或非秘密 runtime config（PowerSync endpoint、上传路径、sync.timeoutMs）变化后自动重启；不可用时 CLI 会返回带 suggested_action 的结构化错误，不会静默回退到另一个进程打开本地 DB。需要明确接受本地缓存语义时，可加 --offline。
• 需要在前台进程打开 PowerSync 的命令（写命令、sync、在线 auth status、--offline 和 --require-sync）会持有跨进程生命周期锁。同一用户数据库上的健康 daemon 会被暂时停止，并且只在前台数据库关闭、owner lease 成功释放后按原端口恢复；使用其他用户数据库的 daemon 不受影响。若关闭或释放失败，CLI 会把 daemon 保持在停止状态并向 stderr 输出清洗后的警告，避免两个运行时同时持有同一 SQLite 数据库。
• dino auth logout 会优先清除保存的凭据；如果当前 shell 仍设置了 DINOX_TOKEN，结果会明确返回 environmentTokenActive: true，该环境仍保持登录。--clear-local-db 只有在 daemon 停止、取得数据库独占所有权并删除主库、WAL、SHM 和 rollback journal 后才会报告成功。任何 owner lease 获取/释放或缓存清理错误都应检查 persistedCredentialsCleared、cleanupPhase 和 cachePaths / cachePath：凭据可能已经清除，但不能据此声称本地清理已安全完成。CLI 会逐个尝试释放所有已取得的 lease；某个 release 失败不会跳过后续 release，也不会覆盖更早的主错误。
• sync.timeoutMs 和 --sync-timeout 只接受 1..2147483647 的十进制整数，避免超过 Node 定时器上限后意外变成约 1ms 超时。
• 更新待办时，建议把 dino todo search 返回的 note_id 作为 dino todo update <taskId> --note-id <noteId> --status completed 的精确定位参数，尤其是 legacy-task-*。legacy id 会绑定搜索时的任务位置和内容；如果笔记结构或任务内容随后变化，CLI 会拒绝旧 id，必须重新搜索，避免改错任务。未传 --note-id 的跨笔记查找最多检查 500 个候选笔记；一旦触顶会返回 TODO_TASK_LOOKUP_TRUNCATED 并拒绝写入，因为此时无法证明 task ID 唯一。遇到该错误时，先运行 dino todo search <task-text> --scan-limit 5000 --format json 找到目标 note_id，再带 --note-id 重试。
• 笔记标签校验、正文 hashtag 解析和标签管理都按当前已解析账号的 user_id 隔离。切换账号后应重新列出或同步标签；只存在于其他账号的同名标签会被视为不存在，不会被当前笔记写入误用。
• dino note detail 的结构化输出包含完整 markdown、纯文本、解析后的 content_json、标签数组和 updated_at，适合在明确需要全文时使用。
• dino storage upload 会把文件写入自定义 S3 并记录资源；图片上传会额外生成 400px webp 缩略图，缩略图 URL 只在命令结果中返回，不写入资源 checksum 字段。显式 --key 默认拒绝覆盖已有主对象或缩略图，只有确认精确替换目标后才使用 --overwrite；key 与存储路径前缀不能包含纯 . / .. 路径段，否则标准 URL 客户端会把地址归一化到错误对象。
• 使用 --overwrite 时，一旦远端对象写入成功，后续缩略图或资源 metadata 记录失败不会自动删除已写入对象。不要把命令失败当作远端已回滚；检查结构化错误详情中的 remoteObjectChanged、affectedKeys 和主对象 storageKey，再核查或重试这些 key。若 S3 PUT 在客户端看来失败但无法确认远端是否已经提交，CLI 会返回 STORAGE_UPLOAD_OUTCOME_UNKNOWN、remoteOutcome: "unknown"、remoteObjectChanged: null 和 possiblyAffectedKeys，并避免对这些可能已写入但没有确认 ETag 的对象做猜测性删除。