Skills

想把 GitHub 或 ZIP 技能包保存到 Dinox？请阅读 技能库：导入与管理；需要从自己的程序下载技能，请阅读 Skills API。本页介绍让 AI 助手操作 Dinox 的 CLI 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

推荐安装与当前 CLI 版本严格匹配的 Skills。先读取 CLI 给出的固定安装命令：

dino info --format json

然后执行 data.skills_install_command。该命令固定安装器版本，固定到与 CLI 相同的 v<version> tag，并显式列出四个 Agent：

npx --yes skills@1.5.16 add ryzencool/dinox-cli-skills#v<version> -g -a codex -a claude-code -a hermes-agent -a openclaw --skill '*' -y

只给单个客户端安装时，保留固定 tag 并只写一个 -a：

全局安装后，各客户端读取的目录分别是 ~/.agents/skills/（Codex）、~/.claude/skills/（Claude Code）、~/.hermes/skills/（Hermes Agent）和 ~/.openclaw/skills/（OpenClaw）。装好后重启对应的 AI 助手。项目级安装（去掉 -g）需要先创建 .hermes/ 和 skills/ 目录，且 Hermes 默认不会发现项目内的 .hermes/skills，因此推荐全局安装。

检查与清理已安装的 Skills

升级 CLI 后，或者 AI 助手的行为和文档对不上时，运行：

dino skills doctor --format json

• data.current 会把每个当前 skill 与 CLI 版本对比，状态包括 current、outdated、missing、foreign（同名但来源不是官方仓库）和 unknown-version。data.current.inSync 为 false 时，执行 data.current.installCommand 即可装上匹配版本。
• data.skills 列出已退役的旧 skill（例如 dinox、manage-tags、search-notes、dino-shared）。这些旧 skill 会和新 skill 争抢触发，并教 AI 使用过时的命令。

清理旧 skill 时先预览，确认无误后再执行：

dino skills migrate --dry-run --format json
dino skills migrate --confirm --format json

migrate 只会移除名称、来源和 skillFolderHash 三者都与官方退役清单完全一致的 skill；标记为 conflict 的同名 skill 会被保留，需要你自己判断。

成功结果的结构如下；_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 --yes skills@1.5.16 add ryzencool/dinox-cli-skills#v<version> -g -a codex -a claude-code -a hermes-agent -a openclaw --skill '*' -y"
  }
}

开始使用

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

方式一：直接说人话

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

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

方式二：指定 skill 名称

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

/dino-note 搜索最近 7 天的 AI 笔记
/dino-note 创建一条标题为「今日笔记」的笔记
/dino-manage-todo 创建待办：联系供应商
/dino-manage-tags reading/tech
/dino-manage-views 创建一个只显示进行中项目的视图
/dino-manage-properties 把这条笔记的状态设为进行中、评分设为 4
/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 版本匹配。
• 失败结果在 stderr 输出结构化错误，包含 code、recoverable、exit_code 和 suggested_action。运行 dino schema errors --format json 可以查看全部错误码及其退出码（1 一般失败、2 用法错误、3 认证、4 同步新鲜度、5 前置条件不满足或资源不存在）。错误码和退出码属于公开契约，只会在大版本中做不兼容变更。
• 读类命令默认使用本地 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 表。
• 保存视图、属性和笔记模板直接复用 Dinox 桌面端的领域代码（schema 校验、filter / sort 编译、属性值转换），因此 CLI 能读写桌面端和 App 创建的所有视图与属性。dino view list/get/fields/query/count/analytics/note-detail/create/update/delete 覆盖完整生命周期：filter 支持 version 1–3（version 2 用于 withinLastDays、isToday、isThisWeek、isThisMonth 动态日期，按 --time-zone 或本机时区计算；version 3 用于 valueRef 指向宿主笔记的 $self 条件），config 支持 table、list、card 三种布局以及 computedColumns、stats、charts、summary 和 noteDetail。--layout 可以只切换布局而不重传 config；sys.title 必须是第一列。
• 创建或更新包含 prop.* 的视图前应先运行 dino view fields --format json：select / status / multi-select filter 必须写稳定 option ID，不能写显示 label；返回的 filterOperators 和 sortable 是每个字段可用的运算符与排序能力。sys.tags 没有 option catalog，带具体 tag 值的 filter 会被拒绝，一次性 tag 查询继续使用 dino note search --tags。
• CLI 无法完整解析的视图（例如更新版本客户端写入的新配置）不会让命令失败：view list 标为 valid: false，view get 返回原始 filterJson / configJson 和错误详情；只改名称、emoji、置顶、排序这类元数据时会原样保留它的 filter 和 config。
• dino view query 按保存的 filter 和 sort 在本地 PowerSync 缓存执行，自动排除软删除和其他账号的笔记。结果在 data.rows[].values 保留原始 property / option ID 与 calc.<id> 计算列，在 data.rows[].displayValues 提供 select / status 标签和卡片盒路径；只有沿 data.nextOffset 翻页直到 data.hasMore: false 后才能声称结果完整。dino view analytics <id> 在整个视图范围（不是当前页）上计算配置好的统计、图表和汇总行；dino view note-detail <noteId> 列出嵌入在该笔记详情里的视图（带 noteDetail 规则、$self 绑定到这条笔记）。
• 视图、属性和模板的写命令都支持 --dry-run 和 --durability <local|uploaded>。dry-run 会在一个最终回滚的事务里真实执行写入，所以预览展示的就是将要保存的内容，同时不会写库，也不会进入上传队列。
• dino prop list/get/create/update/delete 管理属性定义，支持 14 种类型：text、number、date、select、multi_select、status、url、email、phone、checkbox、files、relation、unique_id、place。属性 key 是写入 c_note.properties 的稳定名称，创建后不可修改，改名只改显示名。prop create 是幂等的：同 key 已存在时复用并合并新选项，类型不同则返回 PROPERTY_DEF_TYPE_CONFLICT。选项只能归档不能删除（--archive-option），可按 id 或 label 重命名、改色；类型配置（日期 / 日期时间、数字格式、select 开放或封闭等）通过 --config 写入桌面端使用的配置记录。删除属性定义不会清除笔记中的值，这些值之后显示为未定义类型。
• dino prop show/set/fill/slots <noteId> 读写笔记属性值。prop set --set key=value 会按属性定义转换并校验：select / status 可以传 label，保存为 option id；数字字符串转为数字；unique_id 自动编号并显示为 PREFIX-n；--unset 或 --patch 中的 null 删除该属性。prop fill 只填写已声明但仍为空的槽位，prop slots 用来声明、清空、删除或重排属性槽位。存储的属性 JSON 损坏时，prop show 返回 valid: false，写入会被拒绝（NOTE_PROPERTIES_CORRUPT），不会被覆盖。旧客户端写入的纯 label 数组选项需要先执行 dino prop migrate-options（先 --dry-run，再用 --confirm --expected-count <n> 执行），它会在同一个事务里为选项分配 id，并改写相关笔记和视图 filter。
• dino template list/get/create/update/delete 管理笔记模板：模板保存正文（Markdown 或 Tiptap JSON）和一组有序的属性 key，不包含默认值。dino note create --template <id> 会把模板正文中的 {{date}}、{{time}}、{{datetime}} 替换为实际值，并把模板的属性 key 声明为空槽位；--properties 写入初始属性值，并和笔记创建放在同一个事务里，任何值不合法都会整体回滚。
• 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 update <id> --title "新标题"（建议先加 --dry-run 预览）。它只改标题，不读取也不改动正文，因此不需要 note content-read + note patch；每次调用只能针对一条笔记。
• 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 的对象做猜测性删除。