Skills

Skills 是一套遵循开放 Agent Skills 规范 的技能包，可用于 Codex、Claude Code、Hermes Agent、OpenClaw 等兼容客户端。装好之后，你可以用一句话让 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

一行命令全局安装；安装器会检测本机支持的 Agent：

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

需要固定安装目标时，使用对应的 Agent 标识：

去掉 -g 就是当前项目安装。安装器会写入各客户端支持的目录：Codex 使用 .agents/skills/，Claude Code 使用 .claude/skills/，Hermes Agent 使用 .hermes/skills/，OpenClaw 使用 skills/。装好后重启对应的 AI 助手。

需要让 Skills 与当前 CLI 版本严格匹配时，先运行：

dino info --format json

然后执行 data.skills_install_command。该命令会固定到与 CLI 相同的 v<version> tag，而不是跟随仓库默认分支。

成功结果的结构如下；_notice 只有存在通知时才会出现在顶层：

{
  "ok": true,
  "data": {
    "version": "<version>",
    "skills_repo": "https://github.com/ryzencool/dinox-cli-skills",
    "skills_version": "<version>",
    "skills_tag": "v<version>",
    "skills_release": "https://github.com/ryzencool/dinox-cli-skills/tree/v<version>",
    "skills_install_command": "npx skills add ryzencool/dinox-cli-skills#v<version> -g"
  }
}

开始使用

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

方式一：直接说人话

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

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

方式二：指定 skill 名称

想更精确地指定操作，可以直接提到 skill 名称。支持 slash command 的客户端也可以使用 / 形式：

/dino-note 搜索最近 7 天的 AI 笔记
/dino-note 创建一条标题为「今日笔记」的笔记
/dino-manage-todo 创建待办：联系供应商
/dino-manage-tags reading/tech
/dino-manage-views 创建一个只显示进行中项目的视图
/dino-sync
dino doctor --format json

能做什么

CLI 行为说明

• 所有 --format json 成功结果都使用 { "ok": true, "data": ... } envelope。命令业务字段必须从 data.* 读取；可选通知位于顶层 _notice，不能把 _notice 当作业务 payload。dino info 的 data.skills_version、data.skills_tag、data.skills_release 和 data.skills_install_command 会与当前 CLI 版本匹配。
• 读类命令默认使用本地 PowerSync 缓存。凡命令 schema 支持 --sync-timeout，Skills 在 Agent 中会默认使用类似 --sync-timeout 20000 的有界预算，并把宿主执行超时设为高 5–10 秒；--offline 或不含同步阶段的命令除外。需要强一致新鲜度时，Skills 会先执行 dino sync --strict --sync-timeout 20000 --format json，或在读命令上添加 --require-sync。严格模式按 PowerSync 的整秒 checkpoint 精度判断本次同步，要求连接有效、下载停止且没有下载错误，并完成本地 token 索引；仍在上传不会阻塞下载新鲜度，因此应看 data.stale、data.downloadIdle、data.tokenIndex.complete 和 data.gate，不能只看兼容字段 data.idle。结构化成功结果会在数据库关闭、owner lease 释放和 daemon 恢复之后输出；宿主先超时时结果是未知，不应直接判定失败或不断放大 CLI timeout，必须先验证新鲜度或写入后置条件。
• 笔记和待办写命令会在 data 中返回 Write Receipt：durability、upload_queue_remaining、version、content_hash、changed 和 stale。默认可以把 data.durability: "local" 视为本地数据库已写入；如果必须等云端上传队列清空，Skills 会加 --durability uploaded，失败时按顶层 code: "UPLOAD_PENDING" 与 suggested_action 处理。
• dino note patch 的 readToken 是短期、单次使用的命令能力（当前有效期为 30 分钟，以 readTokenExpiresAt 为准），并绑定生成它时当前账号对应的本地 PowerSync 数据库作用域，不能在切换账号或本地数据库后复用。任何真实 patch 尝试都会先原子消费 token；失败后必须重新执行 dino note content-read <id>。默认读取只返回 block 类型、范围、hash 和字符数，并标记 readTokenScope: "structural-metadata"；只有用户授权全文读取并添加 --include-content 时，才返回完整 Markdown、详细 blocks 和 readTokenScope: "full-content"。媒体、表格、容器或未知 block 的 --allow-protected-replace 只接受已审阅全文后取得的 full-content token。Agent 必须把 token 放进唯一、mode 0600 的临时文件，通过 --read-token @<file> 传入，并在单次真实尝试后立即删除，不能写入 argv、日志、笔记或可复用文件。
• CLI 2.0 的结构化读取契约统一使用 freshness envelope：dino note get 只返回轻量 data.note，dino note detail 始终返回 data.stale、data.count、data.notes，dino prompt list 返回 data.prompts，dino box list 返回 data.boxes。从 1.x 升级的脚本需要按这些字段迁移，不能继续把 detail/list 的 data 当作裸对象或裸数组。
• 笔记星标的 canonical 字段是 starred_at：打星会写入当前 UTC 时间，取消星标会写入 null。is_starred 仍作为便于 Agent 和脚本判断的派生布尔值返回；dino note search --fields 可同时选择 starred_at 和 is_starred，SQL-like 的 is_starred 条件也会转换为对 starred_at 的判断。
• dino note detail 和 JSON 导出会返回与桌面端一致的 properties、is_pub、starred_at 和派生 is_starred。CLI 的 PowerSync schema 与 Electron 的 48 张 canonical 表保持字段、类型、local-only 标记和索引一致；CLI 只额外维护两张用于本地全文索引游标的 local-only 表。
• 保存视图使用与 Electron 一致的严格 version 1 契约。dino view list/get/fields/query/count/create/update/delete 覆盖 catalog、定义、字段发现、分页查询、计数和完整生命周期；--filter 与 --config 支持 inline JSON 或 @file，只接受 layout: "table"，并要求 sys.title 是第一列。创建或更新包含 prop.* 的视图前应先运行 dino view fields --format json：select / multi-select filter 必须写稳定 option ID，不能写显示 label；multi-select、relation、sys.tags 和 sys.zettel_boxes 不能排序。日期条件会在 JavaScript 日期归一化前按 Electron 规则校验真实日历日期，使用大写 T 或小写 t 的 ISO 时间都不会接受不存在的日期。当前 Electron 语义无法为 sys.tags 提供 option catalog，因此 CLI 会拒绝带具体 tag 值的保存视图 filter，避免写入桌面端无法执行的定义；一次性 tag 查询继续使用 dino note search --tags。
• dino view query 按保存的 filter 和 sort 在本地 PowerSync 缓存执行，自动排除软删除和其他账号的笔记。结果在 data.rows[].values 保留原始 property / option ID，在 data.rows[].displayValues 提供 select 标签元数据；只有沿 data.nextOffset 翻页直到 data.hasMore: false 后才能声称结果完整。视图 create/update/delete 都支持 --dry-run 和 --durability <local|uploaded>，软删除不会永久移除数据。
• dino doctor --format json 会在 data 中返回认证、同步、上传队列、笔记 FTS 索引对账、daemon 版本 / 账号 / token 指纹 / runtime config 匹配和本地数据库完整性状态；dino doctor --fix --format json 会尝试清空上传队列、重建本地笔记索引并重启 stale daemon。CLI 会先释放数据库 owner lease 再重启 daemon；失败的修复会保持 data.healthy: false，不会被标记为已修复。
• 结构化错误写入 stderr，并在顶层返回 code、recoverable、exit_code 和 suggested_action；详细错误对象位于 error。脚本可以按退出码分支：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 的对象做猜测性删除。