# @dinoxx/dinox-cli 中文文档

规范地址：https://npmcn.com/package/%40dinoxx/dinox-cli/

版本：2\.19\.0
npm 元数据更新时间：2026-11-05T11:12:30.492Z
中文译文更新时间：2026-11-12T10:21:02.849Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dinoxx/dinox-cli
原文对照：https://npmcn.com/package/%40dinoxx/dinox-cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.8 MB，498 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0 \<26\.0\.0
- 运行依赖：45 个
- 首次发布：2026-03-01T16:22:09.329Z
- 最新版本发布：2026-11-05T11:12:30.313Z
- 近 30 天下载量：4240（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

丁诺克CLI

## 安装

```sh
npm install @dinoxx/dinox-cli
```

也可以使用：`pnpm add @dinoxx/dinox-cli`、`yarn add @dinoxx/dinox-cli`、`bun add @dinoxx/dinox-cli`

## README

# Dinox CLI 用户手册

`dino` 是 Dinox 的命令行工具，用来在本地管理和同步你的 Dinox 数据，包括：笔记、待办、标签、卡片盒、Prompt、知识图谱，以及适合脚本和 AI 助手调用的结构化命令输出。

这份 README 按“先上手、再进阶、最后查表”的顺序重写，尽量做到：

-   先让你快速跑通第一次使用
-   再教你完成最常见的日常操作
-   最后给出完整命令速查，方便回头查阅

如果你只想尽快开始，先看“5 分钟快速上手”。

* * *

## 目录

-   [1\. 你可以用 Dinox CLI 做什么](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-1-%E4%BD%A0%E5%8F%AF%E4%BB%A5%E7%94%A8-dinox-cli-%E5%81%9A%E4%BB%80%E4%B9%88)
-   [2\. 安装要求与安装方法](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-2-%E5%AE%89%E8%A3%85%E8%A6%81%E6%B1%82%E4%B8%8E%E5%AE%89%E8%A3%85%E6%96%B9%E6%B3%95)
-   [3\. 5 分钟快速上手](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-3-5-%E5%88%86%E9%92%9F%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B)
-   [4\. 使用前必须知道的 6 个规则](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-4-%E4%BD%BF%E7%94%A8%E5%89%8D%E5%BF%85%E9%A1%BB%E7%9F%A5%E9%81%93%E7%9A%84-6-%E4%B8%AA%E8%A7%84%E5%88%99)
-   [5\. 日常操作教程](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-5-%E6%97%A5%E5%B8%B8%E6%93%8D%E4%BD%9C%E6%95%99%E7%A8%8B)
-   [6\. 完整命令速查](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-6-%E5%AE%8C%E6%95%B4%E5%91%BD%E4%BB%A4%E9%80%9F%E6%9F%A5)
-   [7\. AI / 脚本自动化](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-7-ai--%E8%84%9A%E6%9C%AC%E8%87%AA%E5%8A%A8%E5%8C%96)
-   [8\. 常见问题](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-8-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)
-   [9\. 配置文件、数据库与环境变量](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-9-%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E6%95%B0%E6%8D%AE%E5%BA%93%E4%B8%8E%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F)
-   [10\. 如何查看帮助](https://npmcn.com/package/%40dinoxx/dinox-cli/#readme-10-%E5%A6%82%E4%BD%95%E6%9F%A5%E7%9C%8B%E5%B8%AE%E5%8A%A9)

* * *

## 1\. 你可以用 Dinox CLI 做什么

Dinox CLI 适合这几类场景：

1.  在终端里登录 Dinox 账号，并把云端数据同步到本地
2.  快速搜索、查看、创建、更新、删除笔记
3.  从笔记里的任务列表中搜索待办，或追加/创建待办
4.  维护标签、卡片盒、Prompt 等结构化信息
5.  查询笔记之间的链接关系和知识图谱
6.  用 `--format json` 输出结构化结果，方便脚本和 AI 调用

你可以把它理解为：

-   普通用户：一个更高效的 Dinox 数据管理工具
-   进阶用户：一个可脚本化的本地知识库命令行入口
-   AI 用户：一个可通过结构化命令和 schema 稳定调用的本地知识库入口

* * *

## 2\. 安装要求与安装方法

### 2.1 系统要求

安装前请先确认：

-   推荐使用 Node.js 24 LTS；支持 Node.js 22、23、24、25（不支持 Node.js 21 及以下或 26+）
-   已安装 npm
-   你的系统可以正常执行全局 npm 命令

检查方法：

```bash
node -v
npm -v
```

### 2.2 安装 Dinox CLI

先确认 `node -v` 是 v22、v23、v24 或 v25，再全局安装。npm 11.16 及以后默认不编译 `better-sqlite3` 和 `sharp`，安装命令要放行这两个包：

```bash
npm install -g @dinoxx/dinox-cli@latest --allow-scripts=better-sqlite3,sharp
```

`npm -v` 低于 11.16 时没有 `--allow-scripts`，去掉这个参数再装。用 pnpm 10.15 及以后时：

```bash
pnpm add -g @dinoxx/dinox-cli@latest --allow-build=better-sqlite3 --allow-build=sharp
```

安装完成后，验证是否成功：

```bash
dino info
```

看到版本号就表示安装成功。

> 说明：安装后通常可以使用 `dino` 或 `dinox` 两个命令名，本文统一使用 `dino`。`dino` 用的是安装时 PATH 里的那个 `node`。

### 2.3 macOS 安装 Node.js（如果你还没装）

Homebrew 的 `node` 公式现在是 Node.js 26，CLI 不能用它。安装 Node.js 24：

```bash
brew install node@24
export PATH="$(brew --prefix node@24)/bin:$PATH"
node -v
```

`node -v` 应显示 v24。再执行上面的安装命令。

### 2.4 Windows 安装 Node.js（如果你还没装）

PowerShell 中可使用：

```powershell
winget install OpenJS.NodeJS.LTS
```

### 2.5 更新 CLI

后续如果要更新到最新版本，直接执行：

```bash
dino update
```

它会安装 `@latest`，所以可以从 1.x 升到 2.x。npm 11.16+ 会自动加上 `--allow-scripts=better-sqlite3,sharp`，pnpm 10.15+ 会自动加上 `--allow-build`。旧版 `dino update` 只在 1.x 里更新，版本停在 1.x 时改用上面的安装命令。

它会自动根据你当前的安装方式选择合适的包管理器执行更新。升级完成后会检查本机已安装的 Agent：有 `claude` 但没有 ACP 命令时安装 `@agentclientprotocol/claude-agent-acp`，有 `codex` 时安装 `@agentclientprotocol/codex-acp`，有 `zcode` 时安装 `zcode-acp`，有 `pi` 时安装 `pi-acp`，有 `agy` 时安装 `agy-acp`，有 `muse` 时安装 `@bex-co/muse-code-acp`。已经装过的适配器会跳过；某个适配器安装失败只给出警告，不影响 CLI 升级本身。

* * *

## 3\. 5 分钟快速上手

下面是第一次使用最推荐的顺序。你可以直接照着执行。

### 第 1 步：登录

在自己的终端运行：

```bash
dino auth login
```

终端会显示二维码。用 Dinox App 打开 **设置 → 设备配对 → 扫一扫**，扫码确认即可。登录时会完成首次同步，之后的读取命令会自动启动本地 daemon，一般不用再手动执行 `dino sync` 或 `dino auth status`。

如果 App 提示二维码无效，先升级 Dinox App。这条命令最长等待 10 分钟。

#### CI / 自动化

没有人可以扫码时，继续用 token。token 可在 App 的 **设置 → 同步设置 → API Token** 获取。

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

说明：

-   `--token-stdin` 接受 token 本体或 `Bearer ...`
-   也可以只在当前进程注入 `DINOX_TOKEN`（优先于本地配置，支持 token 本体或 `Bearer ...`），不写入配置文件

### 第 2 步：搜索一条笔记试试

```bash
dino note search "AI"
```

### 第 3 步：新建一条笔记试试

```bash
dino note create \
  --title "今天的记录" \
  --content "# 标题\n\n这里是正文" \
  --type note
```

如果你能顺利完成上面 3 步，说明 CLI 已经可以正常使用。

* * *

## 4\. 使用前必须知道的 6 个规则

很多问题都来自对 CLI 约定不熟。先掌握下面 6 条，会少踩很多坑。

### 规则 1：很多命令默认会优先使用本地数据库

`dino sync` 会把云端数据同步到本地。后续大多数查询命令会基于本地缓存工作。

如果你希望明确只使用本地缓存、不触发联网/同步，可以加：

```bash
--offline
```

例如：

```bash
dino note search "项目复盘" --offline
```

适用场景：

-   网络不稳定
-   只想查本地缓存
-   你已经先手动执行过 `dino sync`

### 规则 2：给脚本或 AI 用时，推荐统一加 `--format json`

例如：

```bash
dino note search "AI" --format json
```

说明：

-   `--format json`：推荐的结构化输出
-   `--format yaml`：也支持
-   `--json`：历史兼容参数，等价于 `--format yaml`

### 规则 3：很多写操作都支持 `--dry-run`

如果你想先看“将会发生什么”，但暂时不真正写入数据，可以用：

```bash
--dry-run
```

例如：

```bash
dino note delete <note-id> --dry-run
```

这对删除、更新、批量修改尤其有用。

### 规则 4：很多参数支持直接从文件读取

凡是写成 `<string|@file>` 或 `<string|@file>` 的参数，通常都支持 `@文件路径` 的写法。

例如从文件读取笔记正文：

```bash
dino note create --title "读书笔记" --content @./note.md --type note
```

例如从文件读取待办列表：

```bash
dino todo create --tasks @./todo.txt
```

### 规则 5：列表参数通常有 3 种写法

像 `--tags`、`--boxes`、`--tasks`、`--ids` 这类列表参数，通常支持：

1.  JSON 数组
2.  逗号分隔
3.  换行分隔

例如这三种都可以：

```bash
--tags '["工作","项目A"]'
--tags "工作,项目A"
--tags @./tags.txt
```

### 规则 6：标签和卡片盒必须先存在，笔记才能引用它们

例如你先创建笔记时用了一个不存在的标签：

```bash
dino note create --title "测试" --content "正文" --tags "工作/项目A"
```

如果这个标签还不存在，就会报错。正确顺序通常是：

```bash
dino tag add "工作/项目A"
dino box add "Inbox"
dino note create --title "测试" --content "正文" --tags "工作/项目A" --boxes "Inbox" --type note
```

* * *

## 5\. 日常操作教程

这一部分按真实使用场景来写。你不需要一开始记住所有命令，先会做日常任务就够了。

### 5.1 搜索笔记

#### 按关键词搜索

```bash
dino note search "AI"
```

#### 搜索最近 7 天的笔记

```bash
dino note search "AI" --days 7
```

#### 按时间范围搜索

```bash
dino note search "AI" --from 2026-03-01 --to 2026-03-31
```

#### 按标签表达式搜索

```bash
dino note search --tags "(work OR life) AND NOT archived"
```

#### 按卡片盒搜索

```bash
dino note search --boxes "Inbox,Project"
```

#### 只看已收藏或未收藏笔记

```bash
dino note search --starred true
dino note search --starred false
```

#### 分页与字段裁剪

```bash
dino note search "AI" --limit 20 --offset 0
dino note search "AI" --fields id,title,summary,created_at
```

#### 高级 SQL 风格筛选

```bash
dino note search --sql 'type = "crawl" AND zettel_boxes IN ("Inbox","Project")'
```

适合场景：

-   你已经很清楚要筛什么字段
-   希望做更复杂的组合条件查询

> 提醒：`--sql` 只支持只读查询条件，不是让你执行任意 SQL。

### 5.2 查看笔记内容

#### 只看笔记基础信息

```bash
dino note get <note-id>
```

#### 只拿轻量上下文（适合 AI / 脚本）

```bash
dino note get <note-id> --format json
```

`note get` 在 2.0 中始终是轻量读取；`--context-only` 仅保留为兼容参数，不会改变输出。

#### 预览正文前几行

```bash
dino note preview <note-id>
dino note preview <note-id> --lines 30
```

#### 查看完整详情

```bash
dino note detail <note-id>
```

#### 批量查看多条笔记详情

```bash
dino note detail --ids @./note-ids.txt
```

### 5.3 创建笔记

#### 创建最简单的一条笔记

```bash
dino note create \
  --title "会议记录" \
  --content "今天讨论了发布计划" \
  --type note
```

#### 从 Markdown 文件创建

```bash
dino note create \
  --title "周报" \
  --content @./weekly.md \
  --type note
```

#### 同时设置标签和卡片盒

```bash
dino note create \
  --title "项目复盘" \
  --content @./review.md \
  --type note \
  --tags "工作/项目A,复盘" \
  --boxes "Project"
```

注意：

-   `--title` 和 `--content` 是必填项
-   `--type` 可选值只有 `note` 和 `crawl`
-   如果你不写 `--type`，默认是 `crawl`
-   如果你想写普通笔记，建议明确加 `--type note`

#### 创建前先预演

```bash
dino note create \
  --title "测试笔记" \
  --content "正文" \
  --type note \
  --dry-run
```

### 5.4 整理笔记元数据与正文

#### `note update`：显式 ID 的全量替换

```bash
dino note update <note-id> --tags "工作,AI" --dry-run
dino note update <note-id> --boxes "Inbox" --starred true --dry-run
```

`note update` 面向明确的笔记 ID，`--tags` 和 `--boxes` 都是完整替换，不是追加。清空标签或卡片盒时传 `[]`：

```bash
dino note update <note-id> --tags '[]'
dino note update <note-id> --boxes '[]'
```

#### `note tag` / `note move`：显式 ID 的增量整理

```bash
dino note tag <note-id> --add "工作,AI" --dry-run
dino note tag --ids @./note-ids.txt --remove "Inbox" --dry-run
dino note move <note-id> --add "Project/Inbox" --dry-run
dino note move --ids @./note-ids.txt --replace "Project" --dry-run
```

`note tag` 管标签，`note move` 管卡片盒归属；它们的 `--add` / `--remove` 会保留现有值，`--replace` 才会覆盖整个列表。`note move` 不移动文件，也不改正文。

#### `note bulk`：按过滤器批量整理

```bash
dino note bulk --tags "Inbox" --tag-add "AI" --format json --dry-run
dino note bulk --days 30 --boxes "Work/Inbox" --box-replace "Archive/Review" --expected-count 12 --confirm --format json
```

`note bulk` 只接受受控过滤器，不支持 `--sql` 作为写入目标筛选。真实写入必须先 dry-run，再带 `--confirm --expected-count <n>`。

#### `note patch`：结构化编辑正文

```bash
dino note patch <note-id> --append-section "复盘" --content @./section.md --format json --dry-run
dino note content-read <note-id> --format json
dino note patch <note-id> --append-section "复盘" --content @./section.md --read-token @/tmp/dinox-read-token-<random> --format json
```

`note patch` 只用于正文结构化编辑。先 dry-run，再在真实写入前执行 `content-read` 并传回 `readToken`。默认 `content-read` 只返回 block 类型、范围、hash 和字符数，不返回 block 文本、预览或 attributes，同时返回 `readTokenScope: "structural-metadata"`。只有用户授权全文读取时才添加 `--include-content`；此时返回 `readTokenScope: "full-content"`。替换媒体、表格、容器、未知节点等受保护 block 时，必须使用已审阅全文后取得的 `full-content` token，并显式添加 `--allow-protected-replace`；默认 scope 会被拒绝。

token 短期有效（当前为 30 分钟，以 `readTokenExpiresAt` 为准），绑定生成它时当前账号对应的本地 PowerSync 数据库作用域，不能在切换账号或本地数据库后复用。token 也是单次使用的，任何真实 patch 尝试都会先消费它，失败后重试必须重新执行 `content-read`。Agent 应把 token 写入唯一、仅 owner 可读写（mode `0600`）的临时文件，通过 `--read-token @<file>` 传入，并在这一次真实 patch 尝试后立即删除；不要把 token 放进命令参数、日志、笔记或可复用文件。

#### 收藏状态

```bash
dino note star <note-id>
dino note unstar <note-id>
dino note star --ids @./note-ids.txt
```

### 5.5 删除笔记

```bash
dino note delete <note-id>
```

说明：

-   这是软删除，不是物理彻底抹除
-   建议先加 `--dry-run` 再执行正式删除

```bash
dino note delete <note-id> --dry-run
```

### 5.6 管理待办任务

Dinox 的待办来自笔记内容中的任务列表。CLI 提供了 4 个最常用动作：搜索、追加、创建、更新状态。

#### 搜索待办

```bash
dino todo search
dino todo search "付款"
dino todo search "付款" --status uncompleted
dino todo search --from 2026-03-01 --to 2026-03-07 --limit 100
```

#### 按标签筛选待办

```bash
dino todo search --tags "工作,财务"
```

#### 创建一条新的待办笔记

```bash
dino todo create "补交报销单"
```

#### 一次创建多条待办

```bash
dino todo create --task "补交报销单" --task "整理发票"
dino todo create --tasks '["补交报销单","整理发票"]'
dino todo create --tasks @./todo.txt --title "本周财务待办"
```

#### 追加待办到现有笔记

```bash
dino todo append "补交报销单"
dino todo append --note-id <note-id> --task "补交报销单" --task "整理发票"
dino todo append --note-id <note-id> --tasks @./todo.txt
```

说明：

-   如果不传 `--note-id`，CLI 会自动选一条“适合追加任务”的最近笔记
-   如果该笔记末尾已有任务列表，会直接并入；没有则会新建任务列表

#### 更新待办状态

```bash
dino todo update <task-id> --status completed
dino todo update <task-id> --note-id <note-id> --status completed
dino todo update <task-id> --status uncompleted
```

兼容写法也支持：

```bash
dino todo update <task-id> --status done
dino todo update <task-id> --status false
```

但为了可读性，推荐始终使用：

-   `completed`
-   `uncompleted`

对没有持久 task id 的旧笔记，`todo search` 会返回 `legacy-task-*` 合成 id。该 id 绑定搜索时的任务位置和内容；如果笔记结构随后变化，更新会安全失败，必须重新搜索，避免把状态写到另一条任务。建议始终把搜索结果中的 `note_id` 一并传给 `--note-id`。

### 5.7 管理标签

#### 查看全部标签

```bash
dino tag list
```

#### 创建标签

```bash
dino tag add "工作/项目A"
dino tag add --name "工作/项目A" --emoji "🧠"
```

说明：

-   支持层级标签，如 `工作/项目A`
-   已删除但同名的标签，CLI 会尽量做恢复而不是重复新建

#### 查看、调整和合并标签层级

```bash
dino tag tree --format json
dino tag stats --format json
dino tag rename "工作/旧项目" "新项目" --format json --dry-run
dino tag move "工作/新项目" --to "归档" --format json --dry-run
dino tag merge "重复标签" "规范标签" --format json --dry-run
dino tag merge "重复标签" "规范标签" --expected-count <affected-count> --confirm --format json
```

`tag merge` 会更新笔记引用并软删除来源子树。真实写入必须使用新鲜 dry-run 返回的 `data.changes.affected_count`，同时提供 `--expected-count` 和 `--confirm`。

### 5.8 管理卡片盒

#### 查看全部卡片盒

```bash
dino box list
```

#### 创建卡片盒

```bash
dino box add "Inbox"
dino box add --name "Inbox" --description "用于存放待整理的想法和资料"
```

说明：

-   `--description` 很值得写
-   这段说明会帮助 AI 和你自己更准确地理解这个卡片盒的用途

#### 查看、调整和合并卡片盒层级

```bash
dino box tree --format json
dino box stats --format json
dino box rename "工作/Inbox" "待整理" --format json --dry-run
dino box move "工作/待整理" --to "归档" --format json --dry-run
dino box merge "工作/重复" "工作/规范" --format json --dry-run
dino box merge "工作/重复" "工作/规范" --expected-count <affected-count> --confirm --format json
```

`box merge` 会更新笔记归属并软删除来源子树，同样要求新鲜 dry-run、`--expected-count` 和 `--confirm`。

### 5.9 管理 Prompt

#### 查看全部 Prompt

```bash
dino prompt list
```

#### 新建 Prompt

```bash
dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报"
dino prompt add --name "周报助手" --prompt @./weekly-prompt.txt
```

### 5.10 查看版本与配置

#### 查看版本信息

```bash
dino info
```

#### 查看全部可读配置

```bash
dino config get
```

#### 查看单个配置项

```bash
dino config get sync.timeoutMs
```

#### 设置同步超时

```bash
dino config set sync.timeoutMs 20000
```

目前最常用、也是正式开放可写的配置项就是：

-   `sync.timeoutMs`

* * *

## 6\. 完整命令速查

这一节适合“我已经知道要做什么，只想确认命令怎么写”。

### 6.1 全局参数

这些参数可以放在很多命令前后使用：

| 参数 | 说明 |
| --- | --- |
| `--format json` | 推荐的结构化输出格式，适合脚本和 AI |
| `--format yaml` | YAML 结构化输出 |
| `--json` | 历史兼容写法，等价于 `--format yaml` |
| `--offline` | 跳过联网/同步，只使用本地缓存 |
| `--sync-timeout <ms>` | 覆盖同步超时时间，单位毫秒 |
| `--verbose` | 预留的详细日志开关 |

示例：

```bash
dino --format json note search "AI"
dino note search "AI" --offline --format json
```

### 6.2 `auth`：登录与状态

```bash
dino auth login
read -rs DINOX_TOKEN
printf '%s' "$DINOX_TOKEN" | dino auth login --token-stdin
unset DINOX_TOKEN
dino auth status
dino auth logout
dino auth logout --clear-local-db
```

用途说明：

-   `login`：不带 token 时在终端显示二维码，用 Dinox App「设置 → 设备配对 → 扫一扫」确认登录；也可以保存 token 并验证连接
-   登录会完成首次同步。CI / 自动化没有扫码条件时，用 `--token-stdin` 或 `DINOX_TOKEN`
-   `status`：查看登录状态、本地库位置、同步状态
-   `logout`：退出登录
-   `logout --clear-local-db`：退出并删除本地 SQLite 缓存
-   logout 会优先清除配置中保存的凭据；若 daemon 停止、身份解析、数据库 owner lease 获取或释放、缓存删除失败，错误详情会返回 `persistedCredentialsCleared`、`cleanupPhase` 和缓存路径。CLI 会尝试释放全部已取得的 lease；即使某个 release 失败，也不会跳过后续 release 或覆盖更早的主错误。此时凭据已清，但不能认为本地清理已安全完成。
-   当前 shell 中的 `DINOX_TOKEN` 不受 logout 影响；结果中的 `environmentTokenActive: true` 表示该环境仍可认证。

### 6.3 `sync`：手动同步

```bash
dino sync
dino sync --sync-timeout 20000
```

用途说明：

-   主动执行一次连接与同步
-   首次使用、网络恢复后、或想刷新本地缓存时最常用
-   `--sync-timeout` 是包含 checkpoint、下载、本地索引和前台运行时准备在内的总预算；AI/CI 外层命令超时应至少比它多几秒
-   上传仍在进行不会阻塞下载新鲜度。判断成功应看 `stale`、`downloadIdle` 和 `gate`，不能只看兼容字段 `idle`
-   结构化成功结果会在数据库关闭、owner lease 释放和 daemon 恢复完成后输出

### 6.4 `note`：笔记管理

#### 搜索与查看

```bash
dino note search [query]
dino note get <id>
dino note get <id> --context-only
dino note preview <id> --lines 30
dino note detail <id>
dino note detail --ids @./ids.txt
```

#### 创建与修改

```bash
dino note create --title "标题" --content @./note.md --type note
dino note update <id> --tags "工作,AI"
dino note update <id> --boxes "Inbox"
dino note update <id> --starred true
dino note star <id>
dino note unstar <id>
dino note delete <id>
```

重点参数：

-   `note search`
    -   `--tags <expr>`：标签表达式
    -   `--from <date>` / `--to <date>` / `--days <n>`：时间过滤
    -   `--starred <true|false>`：按收藏状态过滤
    -   `--boxes <list>`：按卡片盒过滤
    -   `--sql <expr>`：高级筛选
    -   `--limit <n>` / `--offset <n>`：分页
    -   `--fields <list>`：裁剪输出字段
    -   `--include-deleted`：包含软删除笔记
-   `note create`
    -   `--title`：必填
    -   `--content`：必填，可用 `@文件`
    -   `--type <note|crawl>`：默认 `crawl`
    -   `--tags` / `--boxes`
    -   `--dry-run`
-   `note update`
    -   `[id]` 或 `--ids`
    -   `--tags` / `--boxes` / `--starred`
    -   `--dry-run`

### 6.5 `todo`：待办管理

```bash
dino todo search [query]
dino todo append [task]
dino todo create [task]
dino todo update <task-id> --status completed
```

重点参数：

-   `todo search`
    -   `--status <all|completed|uncompleted>`
    -   `--tags <list>`
    -   `--from <date>` / `--to <date>` / `--days <n>`
    -   `--limit <n>`
    -   `--scan-limit <n>`
    -   `--include-deleted`
-   `todo append`
    -   `[task]` / `--task` / `--tasks`
    -   `--note-id <id>`
    -   `--dry-run`
-   `todo create`
    -   `[task]` / `--task` / `--tasks`
    -   `--title <string>`
    -   `--dry-run`
-   `todo update`
    -   `--status <status>` 必填
    -   `--note-id <id>`：用搜索结果中的笔记 id 精确限定目标
    -   `--dry-run`

### 6.6 `tag`：标签管理

```bash
dino tag list
dino tag add "工作/项目A"
dino tag add --name "工作/项目A" --emoji "🧠"
```

### 6.7 `box`：卡片盒管理

```bash
dino box list
dino box add "Inbox"
dino box add --name "Inbox" --description "用于存放待整理资料"
```

重点参数：

-   `--description <string>`：用途说明
-   `--color <string>`：颜色
-   `--dry-run`

### 6.8 `prompt`：Prompt 管理

```bash
dino prompt list
dino prompt add --name "周报助手" --prompt "请基于本周笔记输出简洁周报"
```

### 6.9 `config`：CLI 配置

```bash
dino config get
dino config get sync.timeoutMs
dino config set sync.timeoutMs 20000
```

### 6.10 `graph`：知识图谱查询

```bash
dino graph backlinks <note-id>
dino graph outlinks <note-id>
dino graph related <note-id> --depth 2
dino graph stats
```

说明：

-   这些命令用于查看笔记之间的链接关系
-   在线模式下，CLI 会自动确保 daemon 可用，并通过 daemon-owned DB runtime 执行
-   如果你只想用本地缓存而不启动 daemon，可加 `--offline`
-   如果 daemon 不可用，默认在线模式会返回带 `suggested_action` 的结构化错误；不会静默回退到另一个进程打开本地 DB

例如：

```bash
dino graph related <note-id> --depth 2 --offline --format json
```

### 6.11 `meta`：查看元数据

```bash
dino meta stats
dino meta schema
```

用途说明：

-   `meta stats`：看 notes / tags / boxes 等统计信息
-   `meta schema`：看 Dinox 结构化数据 schema，适合 AI / 自动化接入

### 6.12 `storage`：自定义存储配置与上传

```bash
dino storage list
dino storage test
dino storage test --storage-id <id>
dino storage upload ./report.pdf
dino storage upload ./photo.jpg --category images
dino storage upload ./report.pdf --key imports/report.pdf --overwrite
dino storage stats
```

重点说明：

-   这是给 Dinox 的自定义存储配置用的，不是一个“任意云盘命令”
-   `storage list` 会列出当前可用的自定义存储，并标出活动配置
-   `storage test` 会测试目标存储是否可写
-   `storage upload` 会上传本地文件，并写入资源记录
-   如果不是上传到当前活动存储，可用 `--storage-id <id>` 指定目标
-   `--category` 支持：`images`、`audios`、`files`、`videos`
-   如果你想自己指定对象 key，可用 `--key <string>`；key 和存储路径前缀不能包含纯 `.` 或 `..` 路径段，否则标准 URL 客户端会把路径归一化到错误对象
-   显式 `--key` 默认拒绝覆盖已有主对象或图片缩略图；只有在确认替换这些精确 key 后才使用 `--overwrite`
-   使用 `--overwrite` 时，一旦远端对象写入成功，后续缩略图或资源 metadata 记录失败不会自动删除已经写入的远端对象。不要把命令失败理解为远端已回滚；请检查结构化错误详情中的 `remoteObjectChanged`、`affectedKeys` 和主对象 `storageKey`，再核查或重试相关 key
-   `--dry-run` 非常适合在正式上传前确认目标位置

### 6.13 `schema`：查看命令 schema

```bash
dino schema
dino schema note.search
dino schema todo.update --format json
```

适合场景：

-   你不确定某个命令的参数怎么写
-   你要让 AI / 脚本可靠调用 CLI
-   你想快速查看命令风险级别、输出结构、示例

### 6.14 `daemon`：管理后台进程

```bash
dino daemon start
dino daemon status
dino daemon restart
dino daemon stop
```

调试时可以前台运行：

```bash
dino daemon start --no-detach
```

`daemon` 是公开 CLI 模块，也可以通过 schema 查询：

```bash
dino schema daemon.start --format json
```

daemon 通过用户数据目录下的私有 Unix domain socket 通信，Windows 使用命名管道；`--port` 仅保留给旧脚本作为兼容字段，不再作为监听地址。

需要在当前进程打开 PowerSync SQLite 的命令（例如写命令、`sync`、在线 `auth status`、`--offline` 或 `--require-sync` 读取）会先取得跨进程生命周期锁。如果同一用户数据库正由健康 daemon 持有，CLI 会暂时停止该实例；只有在命令结束、数据库关闭且 owner lease 成功释放后，才会按原端口恢复它。使用其他用户数据库的 daemon 不会被停止；如果关闭或释放失败，CLI 会保留 daemon 为停止状态并在 stderr 报告警告，避免两个运行时同时持有同一 SQLite 数据库。

### 6.15 `gateway`：把本机 Agent 挂成远程设备

在 Dinox App 中为每个 Agent 选择工作目录；会话始终保留开始时的目录，开启新话题也不改变。App 可以浏览该会话在这台电脑上的目录。

```bash
dino gateway detect
dino gateway detect --add
dino gateway add Hermes --command hermes --arg acp
dino gateway list
dino gateway status
dino gateway reload
dino gateway remove Hermes
```

`detect` 会在 `PATH` 上查找 ACP agent，并用真实握手确认能否启动。覆盖范围与 [Paseo 的 ACP catalog](https://github.com/getpaseo/paseo/blob/main/packages/app/src/data/acp-provider-catalog.ts) 对齐，另外包含 Pi（`pi-acp`）、Antigravity（`agy-acp`）、Muse Code（`muse-code-acp`）和 OMP（`omp acp`）。只认本机已经装好的命令，不会为了探测去 `npx -y` 下载。每个 agent 一握手完就打印，不用等最慢的那个。某个启动方式一直不应答时，不再换参数重试。`--add` 把已确认的 agent 写入当前账号的 gateway 配置，并由 daemon 托管。`gateway list` 只显示环境变量名，不显示值。`dino gateway mcp` 由这些 agent 拉起，对外提供笔记、待办、标签、卡片盒等读写工具，以及把本机文件放进回复的 `send_file`。账号、同步、守护进程和 gateway 自身的命令不在这套工具里。

### 6.16 `info`：查看版本与技能仓库地址

```bash
dino info
```

### 6.17 `update`：升级 CLI

```bash
dino update
```

升级 CLI 之后，会为本机已有、但还没有 ACP 命令的 Agent 安装适配器（Claude Code、Codex、ZCode）。`--format json` 的 `acpAdapters` 返回每一项的 `installed` 或 `failed`。

* * *

## 7\. AI / 脚本自动化

如果你希望让 AI 助手或脚本可靠调用 Dinox 数据，推荐直接使用 CLI 命令的结构化输出。

### 7.1 使用 JSON 输出

```bash
dino note search "dinox" --limit 5 --format json
dino note detail <id> --format json
dino todo search --status uncompleted --format json
```

`--format json` 会返回稳定的结构化 envelope，适合被脚本、自动化任务和 AI Agent 解析。

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` 读取；两者同时返回 `data.stale` 和 `data.count`。
-   所有 structured dry-run 都会返回 `data.stale` 和 `data.sync.gate`，用于判断预览是否建立在新鲜数据上。

Agent 调用在线命令时，只要 schema 提供 `--sync-timeout`，建议传入有界预算（例如 `20000`），并把宿主工具超时设为高 5–10 秒。宿主先超时但没有收到 structured envelope 时，结果是未知，不要直接重试写入；先检查新鲜度或写入后置条件。

### 7.2 先读取命令 schema

不确定某个命令支持哪些参数、输出哪些字段时，先读取 schema：

```bash
dino schema
dino schema note.search --format json
dino schema todo.update --format json
```

schema 包含命令路径、风险级别、参数、选项、输出字段和示例。写操作建议先使用 `--dry-run` 确认结果。

* * *

## 8\. 常见问题

### Q1：安装或升级后出现 `allowScripts` / `Ignored build scripts`，或者一用就报 `better-sqlite3`

原因：本地数据库依赖 `better-sqlite3`，图片处理依赖 `sharp`。npm 11.16+ 和 pnpm 10.15+ 默认不运行这两个包的安装脚本，本机程序就没有装上。Node.js 26 也不在支持范围内，Homebrew 的 `brew install node` 现在装的就是 26。

解决：换成 Node.js 24，再重新安装。

```bash
node -v
npm install -g @dinoxx/dinox-cli@latest --allow-scripts=better-sqlite3,sharp
dino info
```

`node -v` 必须是 v22 到 v25。黄字警告本身不是升级失败；版本号没有变成最新版时，用上面这条命令，不要继续用旧的 `dino update`。

### Q2：报错 `Missing resolved userId for the current authorization`

原因：你还没有完成登录，或当前 `DINOX_TOKEN` 环境变量覆盖了本地 token，CLI 需要先在线解析这个 token 对应的用户身份。

解决：在自己的终端运行 `dino auth login`，用 Dinox App 扫码。CI 或已有 token 时：

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

如果你使用环境变量登录，确认 `DINOX_TOKEN` 已设置后直接运行一次在线命令：

```bash
dino auth status --format json
dino sync
```

### Q3：创建笔记时报 `Unknown tags` 或 `Unknown zettel box names`

原因：你引用了不存在的标签或卡片盒。

解决：先创建，再重试。

```bash
dino tag add "你的标签"
dino box add "你的卡片盒"
```

### Q4：我已经同步过了，能不能完全离线查询？

可以。很多读命令都支持：

```bash
--offline
```

例如：

```bash
dino note search "日报" --offline
dino graph stats --offline --format json
```

前提是：你之前至少成功同步过一次，本地缓存里已经有数据。

### Q5：`note update` 为什么不是“追加标签”？

因为它的设计就是“全量替换”。

例如：

```bash
dino note update <note-id> --tags "工作,AI"
```

执行后，目标笔记的标签会被替换成这两个，而不是在原来基础上追加。

追加标签请使用：

```bash
dino note tag <note-id> --add "工作,AI"
```

### Q6：`todo append` 不传 `--note-id` 时会发生什么？

CLI 会自动选一条最近的、适合追加任务的笔记作为目标。

如果你不希望它自动选，最稳妥的做法是显式传：

```bash
dino todo append --note-id <note-id> --task "补交报销单"
```

### Q7：Windows 下 `@file` 参数解析不稳定怎么办？

在 PowerShell 中，建议把 `@文件路径` 放进引号里。

例如：

```powershell
dino note create --title "测试" --content "@.\note.md" --type note
```

### Q8：怎么知道某个命令到底支持哪些参数？

最直接的方法：

```bash
dino <命令> --help
```

如果你想看更结构化的 schema：

```bash
dino schema
dino schema note.search
dino schema todo.update --format json
```

* * *

## 9\. 配置文件、数据库与环境变量

### 9.1 默认文件位置

#### macOS

-   配置文件：`~/Library/Application Support/dinox/config.json`
-   本地数据库：`~/Library/Application Support/dinox/dinox-cli.sqlite`

#### Windows

-   配置文件：`%APPDATA%\dinox\config.json`
-   本地数据库：`%LOCALAPPDATA%\dinox\dinox-cli.sqlite`

#### Linux

-   配置文件：`~/.config/dinox/config.json`
-   本地数据库：`~/.local/share/dinox/dinox-cli.sqlite`

### 9.2 常用环境变量

| 环境变量 | 用途 |
| --- | --- |
| `DINOX_CONFIG_DIR` | 覆盖配置目录 |
| `DINOX_DATA_DIR` | 覆盖本地数据目录 |
| `DINOX_TOKEN` | 用环境变量注入登录 token，优先级高于本地配置；可传 token 本体或 `Bearer ...` |
| `DINOX_SYNC_TIMEOUT_MS` | 覆盖同步超时 |
| `DINOX_DAEMON_AUTO_INSTALL` | 设为 `0` 时，`auth login` / `gateway add` 不再自动把 daemon 安装为登录服务 |

### 9.3 macOS / Linux 与 Windows 的多行命令差异

#### macOS / Linux（bash / zsh）

用反斜杠 `\` 续行：

```bash
dino note create \
  --title "标题" \
  --content "正文" \
  --type note
```

#### Windows PowerShell

用反引号 `` ` `` 续行：

```powershell
dino note create `
  --title "标题" `
  --content "正文" `
  --type note
```

* * *

## 10\. 如何查看帮助

任何时候都可以直接看 CLI 帮助：

```bash
dino --help
dino help note
```

更常见的写法是：

```bash
dino note --help
dino note create --help
dino todo --help
dino storage upload --help
```

如果你是脚本作者或 AI Agent 开发者，强烈建议搭配这两个命令一起使用：

```bash
dino schema
dino schema <path> --format json
```

* * *

如果你是第一次用，建议按下面顺序熟悉：

1.  `dino auth login`
2.  `dino note search`
3.  `dino note create`
4.  `dino todo search`
5.  `dino tag add` / `dino box add`
6.  `dino schema`

这样会最快建立完整使用感。

## 常见问题

### @dinoxx/dinox-cli 是什么？

丁诺克CLI

### 如何安装 @dinoxx/dinox-cli？

在项目目录运行 npm install @dinoxx/dinox-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dino、dinox，可以用 npx dino 直接运行。

### @dinoxx/dinox-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dinoxx/dinox-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dinoxx/dinox-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0 \<26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dinoxx/dinox-cli 可以商用吗？

@dinoxx/dinox-cli 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dinoxx/dinox-cli 的下载量有多少？

根据 npm 官方下载统计，@dinoxx/dinox-cli 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,240 次，日均约 141 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dinoxx/dinox-cli 还在维护吗？

最新版本 2\.19\.0 发布于 2026/11/05（6 天前）；至今共发布 54 个版本，其中过去 12 个月发布了 54 个；首次发布于 2026/03/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。