@dinoxx/dinox-cli 1.0.19 → 1.0.21

package/README.md

@@ -1,840 +1,1124 @@
-# Dinox CLI 使用说明（普通用户版）
+# Dinox CLI 用户手册
 
-`dino` 是一个命令行工具，用来管理你的 Dinox 数据（笔记、标签、卡片盒等）。
+`dino` 是 Dinox 的命令行工具，用来在本地管理和同步你的 Dinox 数据，包括：笔记、待办、标签、卡片盒、Prompt、知识图谱，以及适合脚本和 AI 助手调用的结构化命令输出。
 
-如果你不熟悉技术细节也没关系，按这份文档一步一步操作就能用。
+这份 README 按“先上手、再进阶、最后查表”的顺序重写，尽量做到：
 
----
+- 先让你快速跑通第一次使用
+- 再教你完成最常见的日常操作
+- 最后给出完整命令速查，方便回头查阅
+
+如果你只想尽快开始，先看“5 分钟快速上手”。
 
-## 1. 先看你要做什么
+---
 
-常见需求：
+## 目录
 
-1. 登录账号：`dino auth login ...`
-2. 同步数据：`dino sync`
-3. 搜索笔记：`dino note search "关键词"`
-4. 搜索待办：`dino todo search ...`
-5. 新建笔记：`dino note create ...`
-6. 新建标签：`dino tag add ...`
-7. 新建卡片盒：`dino box add ...`
-8. 看当前版本：`dino info`
+- [1. 你可以用 Dinox CLI 做什么](#1-你可以用-dinox-cli-做什么)
+- [2. 安装要求与安装方法](#2-安装要求与安装方法)
+- [3. 5 分钟快速上手](#3-5-分钟快速上手)
+- [4. 使用前必须知道的 6 个规则](#4-使用前必须知道的-6-个规则)
+- [5. 日常操作教程](#5-日常操作教程)
+- [6. 完整命令速查](#6-完整命令速查)
+- [7. AI / 脚本自动化](#7-ai--脚本自动化)
+- [8. 常见问题](#8-常见问题)
+- [9. 配置文件、数据库与环境变量](#9-配置文件数据库与环境变量)
+- [10. 如何查看帮助](#10-如何查看帮助)
 
 ---
 
-## 2. 安装前准备
+## 1. 你可以用 Dinox CLI 做什么
 
-你需要先安装 Node.js（建议 LTS，且版本 >= 20）。
+Dinox CLI 适合这几类场景：
 
-检查是否已安装：
+1. 在终端里登录 Dinox 账号，并把云端数据同步到本地
+2. 快速搜索、查看、创建、更新、删除笔记
+3. 从笔记里的任务列表中搜索待办，或追加/创建待办
+4. 维护标签、卡片盒、Prompt 等结构化信息
+5. 查询笔记之间的链接关系和知识图谱
+6. 用 `--format json` 输出结构化结果，方便脚本和 AI 调用
 
-```bash
-node -v
-npm -v
-```
+你可以把它理解为：
+
+- 普通用户：一个更高效的 Dinox 数据管理工具
+- 进阶用户：一个可脚本化的本地知识库命令行入口
+- AI 用户：一个可通过结构化命令和 schema 稳定调用的本地知识库入口
 
 ---
 
-## 3. 安装方法（macOS / Windows）
+## 2. 安装要求与安装方法
+
+### 2.1 系统要求
 
-## 3.1 macOS
+安装前请先确认：
 
-### 方式 A：普通用户推荐（全局安装）
+- 已安装 Node.js 20 或更高版本
+- 已安装 npm
+- 你的系统可以正常执行全局 npm 命令
 
-1. 安装 Node.js（若未安装）：
+检查方法：
 
 ```bash
-brew install node
+node -v
+npm -v
 ```
 
-2. 安装 CLI：
+### 2.2 安装 Dinox CLI
+
+推荐直接全局安装：
 
 ```bash
 npm install -g @dinoxx/dinox-cli
 ```
 
-3. 验证：
+安装完成后，验证是否成功：
 
 ```bash
 dino info
 ```
 
----
-
-## 3.2 Windows
+看到版本号就表示安装成功。
 
-### 方式 A：普通用户推荐（全局安装）
+> 说明：安装后通常可以使用 `dino` 或 `dinox` 两个命令名，本文统一使用 `dino`。
 
-1. 安装 Node.js（若未安装）：
+### 2.3 macOS 安装 Node.js（如果你还没装）
 
-```powershell
-winget install OpenJS.NodeJS.LTS
+```bash
+brew install node
 ```
 
-2. 安装 CLI（PowerShell 或 CMD）：
+### 2.4 Windows 安装 Node.js（如果你还没装）
+
+PowerShell 中可使用：
 
 ```powershell
-npm install -g @dinoxx/dinox-cli
+winget install OpenJS.NodeJS.LTS
 ```
 
-3. 验证：
+### 2.5 更新 CLI
 
-```powershell
-dino info
+后续如果要更新到最新版本，直接执行：
+
+```bash
+dino update
 ```
 
+它会自动根据你当前的安装方式选择合适的包管理器执行更新。
+
 ---
 
-## 4. 第一次使用（建议照抄）
+## 3. 5 分钟快速上手
+
+下面是第一次使用最推荐的顺序。你可以直接照着执行。
 
-## 第 1 步：登录
+### 第 1 步：登录
 
 ```bash
-dino auth login "<你的token>"
+dino auth login "<你的 token>"
 ```
 
-## 第 2 步：同步
+说明：
+
+- 这里填的是登录 token 本体
+- `dino auth login` 建议传 token 本体，不要加 `Bearer ` 前缀
+- 登录时 CLI 会顺便验证连接是否可用
+- 自动化或 CI 可以改用 `DINOX_TOKEN` 环境变量注入 token；它优先于本地配置，并支持 token 本体或 `Bearer ...`
+
+### 第 2 步：同步数据到本地
 
 ```bash
 dino sync
 ```
 
-## 第 3 步：看状态（可选）
+这一步会把 Dinox 数据同步到本地 SQLite 数据库，后续很多查询都会直接使用本地缓存。
+
+### 第 3 步：确认当前状态
 
 ```bash
 dino auth status
 ```
 
+你会看到当前是否已登录、本地数据库位置、最近同步状态等信息。
+
+### 第 4 步：搜索一条笔记试试
+
+```bash
+dino note search "AI"
+```
+
+### 第 5 步：新建一条笔记试试
+
+```bash
+dino note create \
+  --title "今天的记录" \
+  --content "# 标题\n\n这里是正文" \
+  --type note
+```
+
+如果你能顺利完成上面 5 步，说明 CLI 已经可以正常使用。
+
 ---
 
-## 5. 最常用命令
+## 4. 使用前必须知道的 6 个规则
+
+很多问题都来自对 CLI 约定不熟。先掌握下面 6 条，会少踩很多坑。
+
+### 规则 1：很多命令默认会优先使用本地数据库
 
-## 5.1 笔记
+`dino sync` 会把云端数据同步到本地。后续大多数查询命令会基于本地缓存工作。
 
-搜索笔记：
+如果你希望明确只使用本地缓存、不触发联网/同步，可以加：
 
 ```bash
-dino note search "AI"
-dino note search "AI" --days 7
-dino note search "AI" --from 2026-02-01 --to 2026-02-28
-dino note search "AI" --boxes "Inbox"
-dino note search --sql 'type = "crawl" AND zettel_boxes IN ("Inbox","Project")'
+--offline
 ```
 
-搜索待办（基于 `image_detail` 的 taskList）：
+例如：
 
 ```bash
-dino todo search
-dino todo search "付款"
-dino todo search "付款" --status uncompleted --tags "工作,财务"
-dino todo search --from 2026-03-01 --to 2026-03-07 --limit 100
+dino note search "项目复盘" --offline
 ```
 
-追加待办到现有笔记：
+适用场景：
+
+- 网络不稳定
+- 只想查本地缓存
+- 你已经先手动执行过 `dino sync`
+
+### 规则 2：给脚本或 AI 用时，推荐统一加 `--format json`
+
+例如：
 
 ```bash
-dino todo append "补交报销单"
-dino todo append --note-id <note-id> --task "补交报销单" --task "整理发票"
-dino todo append --tasks '["补交报销单","整理发票"]'
+dino note search "AI" --format json
 ```
 
-创建新的待办笔记：
+说明：
+
+- `--format json`：推荐的结构化输出
+- `--format yaml`：也支持
+- `--json`：历史兼容参数，等价于 `--format yaml`
+
+### 规则 3：很多写操作都支持 `--dry-run`
+
+如果你想先看“将会发生什么”，但暂时不真正写入数据，可以用：
 
 ```bash
-dino todo create "补交报销单"
-dino todo create --task "补交报销单" --task "整理发票" --title "本周财务待办"
-dino todo create --tasks @./todo.txt
+--dry-run
 ```
 
-更新待办完成状态：
+例如：
 
 ```bash
-dino todo update <task-id> --status completed
-dino todo update <task-id> --status uncompleted
+dino note delete <note-id> --dry-run
 ```
 
-创建笔记：
+这对删除、更新、批量修改尤其有用。
+
+### 规则 4：很多参数支持直接从文件读取
+
+凡是写成 `<string|@file>` 或 `<string|@file>` 的参数，通常都支持 `@文件路径` 的写法。
+
+例如从文件读取笔记正文：
 
 ```bash
-dino note create \
-  --title "今天的记录" \
-  --content "# 标题\n\n正文内容"
+dino note create --title "读书笔记" --content @./note.md --type note
 ```
 
-按 ID 查看：
+例如从文件读取待办列表：
 
 ```bash
-dino note get <note-id>
-dino note detail <note-id>
+dino todo create --tasks @./todo.txt
 ```
 
-删除笔记（软删除）：
+### 规则 5：列表参数通常有 3 种写法
+
+像 `--tags`、`--boxes`、`--tasks`、`--ids` 这类列表参数，通常支持：
+
+1. JSON 数组
+2. 逗号分隔
+3. 换行分隔
+
+例如这三种都可以：
 
 ```bash
-dino note delete <note-id>
+--tags '["工作","项目A"]'
+--tags "工作,项目A"
+--tags @./tags.txt
 ```
 
-## 5.2 标签
+### 规则 6：标签和卡片盒必须先存在，笔记才能引用它们
 
-列出标签：
+例如你先创建笔记时用了一个不存在的标签：
 
 ```bash
-dino tag list
+dino note create --title "测试" --content "正文" --tags "工作/项目A"
 ```
 
-新增标签（两种写法都可以）：
+如果这个标签还不存在，就会报错。正确顺序通常是：
 
 ```bash
 dino tag add "工作/项目A"
-dino tag add --name "工作/项目A" --emoji "🧠"
+dino box add "Inbox"
+dino note create --title "测试" --content "正文" --tags "工作/项目A" --boxes "Inbox" --type note
 ```
 
-## 5.3 卡片盒
+---
+
+## 5. 日常操作教程
+
+这一部分按真实使用场景来写。你不需要一开始记住所有命令，先会做日常任务就够了。
+
+### 5.1 搜索笔记
 
-列出卡片盒：
+#### 按关键词搜索
 
 ```bash
-dino box list
+dino note search "AI"
 ```
 
-新增卡片盒（两种写法都可以）：
+#### 搜索最近 7 天的笔记
 
 ```bash
-dino box add "Inbox"
-dino box add --name "Inbox" --description "用于存放待整理的想法和资料"
+dino note search "AI" --days 7
 ```
 
-`--description` 很有用：它能帮助 AI 更准确地把笔记分到正确卡片盒。
-
-## 5.4 Prompt
+#### 按时间范围搜索
 
 ```bash
-dino prompt list
-dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报"
+dino note search "AI" --from 2026-03-01 --to 2026-03-31
 ```
 
-## 5.5 配置
+#### 按标签表达式搜索
+
+```bash
+dino note search --tags "(work OR life) AND NOT archived"
+```
 
-查看全部配置：
+#### 按卡片盒搜索
 
 ```bash
-dino config get
+dino note search --boxes "Inbox,Project"
 ```
 
-查看某一项：
+#### 只看已收藏或未收藏笔记
 
 ```bash
-dino config get sync.timeoutMs
+dino note search --starred true
+dino note search --starred false
 ```
 
-设置某一项：
+#### 分页与字段裁剪
 
 ```bash
-dino config set sync.timeoutMs 20000
+dino note search "AI" --limit 20 --offset 0
+dino note search "AI" --fields id,title,summary,created_at
 ```
 
----
+#### 高级 SQL 风格筛选
 
-## 6. macOS 和 Windows 的使用差异
+```bash
+dino note search --sql 'type = "crawl" AND zettel_boxes IN ("Inbox","Project")'
+```
 
-## 6.1 路径位置不同
+适合场景：
 
-配置文件：
+- 你已经很清楚要筛什么字段
+- 希望做更复杂的组合条件查询
 
-1. macOS: `~/Library/Application Support/dinox/config.json`
-2. Windows: `%APPDATA%\dinox\config.json`
+> 提醒：`--sql` 只支持只读查询条件，不是让你执行任意 SQL。
 
-## 6.2 多行命令写法不同
+### 5.2 查看笔记内容
 
-macOS / Linux（bash/zsh）用 `\` 续行：
+#### 只看笔记基础信息
 
 ```bash
-dino note create \
-  --title "标题" \
-  --content "正文"
+dino note get <note-id>
 ```
 
-Windows PowerShell 用反引号 `` ` `` 续行：
+#### 只拿轻量上下文（适合 AI / 脚本）
 
-```powershell
-dino note create `
-  --title "标题" `
-  --content "正文"
+```bash
+dino note get <note-id> --context-only --format json
 ```
 
-## 6.3 `@file` 参数在 Windows 建议加引号
+#### 预览正文前几行
+
+```bash
+dino note preview <note-id>
+dino note preview <note-id> --lines 30
+```
 
-比如从文件读取正文：
+#### 查看完整详情
 
 ```bash
-dino note create --title "测试" --content @./note.md
+dino note detail <note-id>
 ```
 
-在 PowerShell 建议写成：
+#### 批量查看多条笔记详情
 
-```powershell
-dino note create --title "测试" --content "@.\note.md"
+```bash
+dino note detail --ids @./note-ids.txt
 ```
 
-这样更稳，不容易被 shell 误解析。
+### 5.3 创建笔记
 
----
+#### 创建最简单的一条笔记
+
+```bash
+dino note create \
+  --title "会议记录" \
+  --content "今天讨论了发布计划" \
+  --type note
+```
 
-## 7. 常见问题
+#### 从 Markdown 文件创建
 
-## Q1：报错 `Missing persisted userId. Run dino auth login first.`
+```bash
+dino note create \
+  --title "周报" \
+  --content @./weekly.md \
+  --type note
+```
 
-你还没有完成登录。执行：
+#### 同时设置标签和卡片盒
 
 ```bash
-dino auth login "<token>"
+dino note create \
+  --title "项目复盘" \
+  --content @./review.md \
+  --type note \
+  --tags "工作/项目A,复盘" \
+  --boxes "Project"
 ```
 
-## Q2：创建笔记时报 `Unknown tags` 或 `Unknown zettel box names`
+注意：
+
+- `--title` 和 `--content` 是必填项
+- `--type` 可选值只有 `note` 和 `crawl`
+- 如果你不写 `--type`，默认是 `crawl`
+- 如果你想写普通笔记，建议明确加 `--type note`
 
-说明你填的标签/卡片盒不存在，先创建再重试：
+#### 创建前先预演
 
 ```bash
-dino tag add "你的标签"
-dino box add "你的卡片盒"
+dino note create \
+  --title "测试笔记" \
+  --content "正文" \
+  --type note \
+  --dry-run
 ```
 
----
+### 5.4 整理笔记元数据与正文
 
-## 8. 完整命令参数参考
+#### `note update`：显式 ID 的全量替换
 
-## 8.1 全局参数（适用于 CLI）
+```bash
+dino note update <note-id> --tags "工作,AI" --dry-run
+dino note update <note-id> --boxes "Inbox" --starred true --dry-run
+```
 
-以下参数可放在命令前后使用，例如：`dino --format json auth status`。
+`note update` 面向明确的笔记 ID，`--tags` 和 `--boxes` 都是完整替换，不是追加。清空标签或卡片盒时传 `[]`：
 
-| 参数 | 类型 | 说明 |
-| --- | --- | --- |
-| `--json` | flag | 兼容旧行为，输出 machine-readable YAML（历史保留写法）。 |
-| `--format <yaml\|json>` | string | 结构化输出格式。推荐 AI / 脚本使用 `--format json`。 |
-| `--offline` | flag | 跳过 connect/sync，仅用本地缓存（仅被支持该参数的命令读取）。 |
-| `--sync-timeout <ms>` | integer | 覆盖连接/同步超时毫秒，必须是正整数。 |
-| `--verbose` | flag | 预留 verbose 开关。 |
+```bash
+dino note update <note-id> --tags '[]'
+dino note update <note-id> --boxes '[]'
+```
 
-## 8.2 `auth` 命令
+#### `note tag` / `note move`：显式 ID 的增量整理
 
-### `dino auth login <token>`
+```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` 不移动文件，也不改正文。
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `<token>` | 是 | 登录 token，直接传 token 字符串（不需要 `Bearer` 前缀）。 |
+#### `note bulk`：按过滤器批量整理
 
-支持全局参数：`--json`、`--format`、`--sync-timeout`
+```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
+```
 
-### `dino auth logout`
+`note bulk` 只接受受控过滤器，不支持 `--sql` 作为写入目标筛选。真实写入必须先 dry-run，再带 `--confirm --expected-count <n>`。
 
-清理已保存登录信息。
+#### `note patch`：结构化编辑正文
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--clear-local-db` | 否 | 同时删除本地 SQLite 数据库。 |
+```bash
+dino note content-read <note-id> --format json
+dino note patch <note-id> --append-section "复盘" --content @./section.md --read-token <token> --format json
+```
 
-### `dino auth status`
+`note patch` 只用于正文结构化编辑。真实写入前必须先 `content-read`，并传回 `readToken`；替换媒体、表格、未知节点等受保护 block 时，还需要显式 `--allow-protected-replace`。
 
-查看当前登录与同步状态。
+#### 收藏状态
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+```bash
+dino note star <note-id>
+dino note unstar <note-id>
+dino note star --ids @./note-ids.txt
+```
 
-## 8.3 `sync` 命令
+### 5.5 删除笔记
 
-### `dino sync`
+```bash
+dino note delete <note-id>
+```
 
-连接并执行同步。
+说明：
 
-支持全局参数：`--json`、`--format`、`--sync-timeout`
+- 这是软删除，不是物理彻底抹除
+- 建议先加 `--dry-run` 再执行正式删除
 
-## 8.4 `schema` 命令
+```bash
+dino note delete <note-id> --dry-run
+```
 
-### `dino schema [path]`
+### 5.6 管理待办任务
 
-查看命令 schema，了解参数、风险级别、输出结构与示例。推荐 AI / 脚本在不确定调用方式时先查看。
+Dinox 的待办来自笔记内容中的任务列表。CLI 提供了 4 个最常用动作：搜索、追加、创建、更新状态。
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[path]` | 否 | 命令路径，例如 `note.search`、`todo.update`、`sync`。不传则列出所有可用 schema。 |
+#### 搜索待办
 
-支持全局参数：`--json`、`--format`
+```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 schema
-dino schema note.search
-dino schema note.search --format json
+dino todo search --tags "工作,财务"
 ```
 
-## 8.5 `note` 命令
+#### 创建一条新的待办笔记
+
+```bash
+dino todo create "补交报销单"
+```
 
-### `dino note search [query]`
+#### 一次创建多条待办
 
-按关键词/标签/创建时间搜索笔记。
+```bash
+dino todo create --task "补交报销单" --task "整理发票"
+dino todo create --tasks '["补交报销单","整理发票"]'
+dino todo create --tasks @./todo.txt --title "本周财务待办"
+```
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[query]` | 否 | 搜索关键词。可为空。 |
+#### 追加待办到现有笔记
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--tags <expr>` | 否 | 标签表达式，支持 `AND` / `OR` / `NOT` 与括号。 |
-| `--from <date>` | 否 | 创建时间起点，支持 `YYYY-MM-DD` 或 ISO datetime。 |
-| `--to <date>` | 否 | 创建时间终点，支持 `YYYY-MM-DD` 或 ISO datetime。 |
-| `--days <n>` | 否 | 最近 N 天（按 `created_at`），不能与 `--from/--to` 同时使用。 |
-| `--boxes <string\|@file>` | 否 | 按卡片盒名称筛选（支持 JSON 数组或逗号/换行分隔）；会自动解析为 box id 查询。 |
-| `--sql <expr>` | 否 | SQL 风格条件表达式；仅支持字段 `id/content_md/summary/tags/zettel_boxes/created_at/type`，其中 `zettel_boxes` 按名称自动转 id。只支持只读 WHERE 条件（禁止 `INSERT/UPDATE/DELETE`、注释和多语句）。 |
-| `--include-deleted` | 否 | 包含软删除笔记。 |
+```bash
+dino todo append "补交报销单"
+dino todo append --note-id <note-id> --task "补交报销单" --task "整理发票"
+dino todo append --note-id <note-id> --tasks @./todo.txt
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+说明：
 
-### `dino note get <id>`
+- 如果不传 `--note-id`，CLI 会自动选一条“适合追加任务”的最近笔记
+- 如果该笔记末尾已有任务列表，会直接并入；没有则会新建任务列表
 
-按 ID 获取笔记基础信息。
+#### 更新待办状态
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[id]` | 否 | 单个笔记 ID（可与 `--ids` 组合，去重后批量更新）。 |
+```bash
+dino todo update <task-id> --status completed
+dino todo update <task-id> --status uncompleted
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+兼容写法也支持：
 
-### `dino note detail [id]`
+```bash
+dino todo update <task-id> --status done
+dino todo update <task-id> --status false
+```
 
-按 ID 获取笔记完整详情，支持批量读取。
+但为了可读性，推荐始终使用：
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[id]` | 否 | 单个笔记 ID（可与 `--ids` 组合，去重后批量读取）。 |
+- `completed`
+- `uncompleted`
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--ids <string\|@file>` | 否 | 笔记 ID 列表（JSON 数组或逗号/换行分隔）。 |
+### 5.7 管理标签
 
-说明：`[id]` 与 `--ids` 至少提供一个。
+#### 查看全部标签
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+```bash
+dino tag list
+```
 
-### `dino note create --title <string> --content <string|@file> [options]`
+#### 创建标签
 
-创建笔记。
+```bash
+dino tag add "工作/项目A"
+dino tag add --name "工作/项目A" --emoji "🧠"
+```
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--title <string>` | 是 | 笔记标题。 |
-| `--content <string|@file>` | 是 | Markdown 内容，可传 `@文件路径`。 |
-| `--type <note\|crawl>` | 否 | 笔记类型，默认 `crawl`。 |
-| `--tags <string\|@file>` | 否 | 标签列表（JSON 数组或逗号/换行分隔）。 |
-| `--boxes <string\|@file>` | 否 | 卡片盒名称列表（JSON 数组或逗号/换行分隔）。 |
-| `--dry-run` | 否 | 仅预览将要创建的笔记，不实际写入。 |
+说明：
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+- 支持层级标签，如 `工作/项目A`
+- 已删除但同名的标签，CLI 会尽量做恢复而不是重复新建
 
-### `dino note update [id] [options]`
+### 5.8 管理卡片盒
 
-按 ID 更新笔记标签/卡片盒（全量替换）。
+#### 查看全部卡片盒
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `<id>` | 是 | 笔记 ID。 |
+```bash
+dino box list
+```
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--ids <string\|@file>` | 否 | 批量更新的笔记 ID 列表（JSON 数组或逗号/换行分隔）。 |
-| `--tags <string\|@file>` | 否 | 标签列表（JSON 数组或逗号/换行分隔）。传 `[]` 可清空标签。 |
-| `--boxes <string\|@file>` | 否 | 卡片盒名称列表（JSON 数组或逗号/换行分隔）。传 `[]` 可清空卡片盒。 |
-| `--starred <true\|false>` | 否 | 设置收藏状态。 |
-| `--dry-run` | 否 | 仅预览将要执行的变更，不实际写入。 |
+#### 创建卡片盒
 
-说明：`<id>` 与 `--ids` 至少提供一个；`--tags` 与 `--boxes` 至少提供一个。
+```bash
+dino box add "Inbox"
+dino box add --name "Inbox" --description "用于存放待整理的想法和资料"
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+说明：
 
-### `dino note delete <id>`
+- `--description` 很值得写
+- 这段说明会帮助 AI 和你自己更准确地理解这个卡片盒的用途
 
-软删除笔记（`is_del=1`）。
+### 5.9 管理 Prompt
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `<id>` | 是 | 笔记 ID。 |
+#### 查看全部 Prompt
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--dry-run` | 否 | 仅预览将要执行的删除，不实际写入。 |
+```bash
+dino prompt list
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+#### 新建 Prompt
 
-## 8.6 `tag` 命令
+```bash
+dino prompt add --name "周报助手" --prompt "请基于本周笔记输出一份简洁周报"
+```
 
-### `dino tag list`
+### 5.10 查看版本与配置
 
-列出标签。
+#### 查看版本信息
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
-| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+```bash
+dino info
+```
 
-### `dino tag add [name] [options]`
+#### 查看全部可读配置
 
-新增标签。
+```bash
+dino config get
+```
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[name]` | 否 | 标签名/路径（支持斜杠层级）。 |
+#### 查看单个配置项
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--name <string>` | 否 | 标签名/路径，可替代位置参数 `[name]`。 |
-| `--emoji <string>` | 否 | 标签 emoji。 |
-| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
-| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
-| `--dry-run` | 否 | 仅预览将要创建或恢复的标签，不实际写入。 |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+```bash
+dino config get sync.timeoutMs
+```
 
-说明：`[name]` 与 `--name` 至少提供一个；若两者都提供且值不同会报错。
+#### 设置同步超时
 
-## 8.7 `box` 命令
+```bash
+dino config set sync.timeoutMs 20000
+```
 
-### `dino box list`
+目前最常用、也是正式开放可写的配置项就是：
 
-列出卡片盒。
+- `sync.timeoutMs`
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+---
 
-### `dino box add [name] [options]`
+## 6. 完整命令速查
 
-新增卡片盒。
+这一节适合“我已经知道要做什么，只想确认命令怎么写”。
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[name]` | 否 | 卡片盒名称。 |
+### 6.1 全局参数
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--name <string>` | 否 | 卡片盒名称，可替代位置参数 `[name]`。 |
-| `--description <string>` | 否 | 用途说明（可帮助 AI 路由笔记）。 |
-| `--color <string>` | 否 | 卡片盒颜色。 |
-| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
-| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
-| `--dry-run` | 否 | 仅预览将要创建或恢复的卡片盒，不实际写入。 |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+这些参数可以放在很多命令前后使用：
 
-说明：`[name]` 与 `--name` 至少提供一个；若两者都提供且值不同会报错。
+| 参数 | 说明 |
+| --- | --- |
+| `--format json` | 推荐的结构化输出格式，适合脚本和 AI |
+| `--format yaml` | YAML 结构化输出 |
+| `--json` | 历史兼容写法，等价于 `--format yaml` |
+| `--offline` | 跳过联网/同步，只使用本地缓存 |
+| `--sync-timeout <ms>` | 覆盖同步超时时间，单位毫秒 |
+| `--verbose` | 预留的详细日志开关 |
 
-## 8.8 `prompt` 命令
+示例：
 
-### `dino prompt list`
+```bash
+dino --format json note search "AI"
+dino note search "AI" --offline --format json
+```
 
-列出 Prompt（`name` 与 `prompt`）。
+### 6.2 `auth`：登录与状态
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+```bash
+dino auth login "<token>"
+dino auth status
+dino auth logout
+dino auth logout --clear-local-db
+```
 
-### `dino prompt add [options]`
+用途说明：
 
-新增 Prompt（写入 `c_cmd`）。
+- `login`：保存 token 并验证连接
+- `status`：查看登录状态、本地库位置、同步状态
+- `logout`：退出登录
+- `logout --clear-local-db`：退出并删除本地 SQLite 缓存
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--name <string>` | 是 | Prompt 名称。 |
-| `--prompt <string>` | 是 | Prompt 文本内容。 |
-| `--json` | 否 | 兼容旧行为，输出 machine-readable YAML。 |
-| `--format <yaml\|json>` | 否 | 结构化输出格式，推荐 AI / 脚本使用 `json`。 |
-| `--dry-run` | 否 | 仅预览将要创建或恢复的 Prompt，不实际写入。 |
-| `--offline` | 否 | 跳过 connect/sync，仅用本地缓存。 |
-| `--sync-timeout <ms>` | 否 | 覆盖连接/同步超时毫秒。 |
+### 6.3 `sync`：手动同步
 
-## 8.9 `config` 命令
+```bash
+dino sync
+dino sync --sync-timeout 600000
+```
 
-### `dino config get [key]`
+用途说明：
 
-读取配置。推荐 AI / 脚本使用 `dino config get [key] --format json`。
+- 主动执行一次连接与同步
+- 首次使用、网络恢复后、或想刷新本地缓存时最常用
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[key]` | 否 | 配置键（点路径）；不传则返回全部配置。 |
+### 6.4 `note`：笔记管理
 
-可读 key：
+#### 搜索与查看
 
-```text
-sync.timeoutMs
+```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
 ```
 
-### `dino config set <key> <value>`
+#### 创建与修改
 
-写入配置。
+```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>
+```
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `<key>` | 是 | 配置键（点路径）。 |
-| `<value>` | 是 | 配置值。 |
+重点参数：
+
+- `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`：待办管理
 
-可写 key：
+```bash
+dino todo search [query]
+dino todo append [task]
+dino todo create [task]
+dino todo update <task-id> --status completed
+```
 
-```text
-sync.timeoutMs    (必须为正整数)
+重点参数：
+
+- `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>` 必填
+  - `--dry-run`
+
+### 6.6 `tag`：标签管理
+
+```bash
+dino tag list
+dino tag add "工作/项目A"
+dino tag add --name "工作/项目A" --emoji "🧠"
 ```
 
-## 8.10 `info` 命令
+### 6.7 `box`：卡片盒管理
 
-### `dino info`
+```bash
+dino box list
+dino box add "Inbox"
+dino box add --name "Inbox" --description "用于存放待整理资料"
+```
+
+重点参数：
 
-显示 CLI 版本信息。
+- `--description <string>`：用途说明
+- `--color <string>`：颜色
+- `--dry-run`
 
-支持全局参数：`--json`、`--format`
+### 6.8 `prompt`：Prompt 管理
 
-## 8.11 `todo` 命令
+```bash
+dino prompt list
+dino prompt add --name "周报助手" --prompt "请基于本周笔记输出简洁周报"
+```
 
-### `dino todo search [query]`
+### 6.9 `config`：CLI 配置
 
-搜索待办任务（任务来源：`c_note.image_detail` 中的 taskItem/taskList）。
+```bash
+dino config get
+dino config get sync.timeoutMs
+dino config set sync.timeoutMs 20000
+```
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[query]` | 否 | 按任务文本模糊匹配（不区分大小写）。 |
+### 6.10 `graph`：知识图谱查询
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--status <status>` | 否 | 任务状态：`all` / `completed` / `uncompleted`（默认 `all`）。 |
-| `--tags <string\|@file>` | 否 | 任务标签筛选（JSON 数组或逗号/换行分隔），任务需包含全部标签。 |
-| `--from <date>` | 否 | 任务时间范围起点（`YYYY-MM-DD` 或 ISO datetime）。 |
-| `--to <date>` | 否 | 任务时间范围终点（`YYYY-MM-DD` 或 ISO datetime）。 |
-| `--days <n>` | 否 | 最近 N 天（不能与 `--from/--to` 同时使用）。 |
-| `--limit <n>` | 否 | 返回任务数上限（默认 `50`，最大 `500`）。 |
-| `--scan-limit <n>` | 否 | 扫描 `c_note` 行数上限（默认 `200`，最大 `5000`）。 |
-| `--include-deleted` | 否 | 包含软删除笔记中的任务。 |
+```bash
+dino graph backlinks <note-id>
+dino graph outlinks <note-id>
+dino graph related <note-id> --depth 2
+dino graph stats
+```
 
-输出结构说明（AI 友好）：
+说明：
 
-- 顶层包含 `meta`（查询条件回显、返回数量、是否截断）与 `tasks`（任务数组）。
-- 每条任务包含 `task_key`、`note_id`、`note_title`、`status`、层级关系与时间字段。
+- 这些命令用于查看笔记之间的链接关系
+- 在线模式下，CLI 会自动确保 daemon 可用
+- 如果你只想用本地缓存而不启动 daemon，可加 `--offline`
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+例如：
 
-### `dino todo append [task]`
+```bash
+dino graph related <note-id> --depth 2 --offline --format json
+```
 
-向笔记末尾追加一个或多个待办任务。
+### 6.11 `meta`：查看元数据
 
-说明：
+```bash
+dino meta stats
+dino meta schema
+```
 
-- `content_json` 是真源，`image_detail` 会从更新后的 `content_json` 派生回写。
-- 若不传 `--note-id`，默认选择 `image_detail` 非空且不为 `[]` 的最新笔记（按 `created_at` 降序）。
-- 若笔记末尾已有 `taskList`，会并入该 `taskList`；否则在末尾创建新的 `taskList`。
+用途说明：
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[task]` | 否 | 单个任务文本。 |
+- `meta stats`：看 notes / tags / boxes 等统计信息
+- `meta schema`：看 Dinox 结构化数据 schema，适合 AI / 自动化接入
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--task <text>` | 否 | 任务文本（可重复传入）。 |
-| `--tasks <string\|@file>` | 否 | 任务列表（JSON 数组或逗号/换行分隔）。 |
-| `--note-id <id>` | 否 | 指定目标笔记 ID。 |
-| `--dry-run` | 否 | 仅预览将要追加的任务和目标笔记，不实际写入。 |
+### 6.12 `storage`：自定义存储配置与上传
 
-说明：`[task]`、`--task`、`--tasks` 至少提供一个。
+```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 stats
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+重点说明：
 
-### `dino todo create [task]`
+- 这是给 Dinox 的自定义存储配置用的，不是一个“任意云盘命令”
+- `storage list` 会列出当前可用的自定义存储，并标出活动配置
+- `storage test` 会测试目标存储是否可写
+- `storage upload` 会上传本地文件，并写入资源记录
+- 如果不是上传到当前活动存储，可用 `--storage-id <id>` 指定目标
+- `--category` 支持：`images`、`audios`、`files`、`videos`
+- 如果你想自己指定对象 key，可用 `--key <string>`
+- `--dry-run` 非常适合在正式上传前确认目标位置
 
-创建一篇新笔记，并写入一个或多个待办任务。
+### 6.13 `schema`：查看命令 schema
 
-说明：
+```bash
+dino schema
+dino schema note.search
+dino schema todo.update --format json
+```
 
-- `content_json` 是真源，`image_detail` 从 `content_json` 派生回写。
-- 默认自动生成总结性标题（可用 `--title` 覆盖）。
+适合场景：
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `[task]` | 否 | 单个任务文本。 |
+- 你不确定某个命令的参数怎么写
+- 你要让 AI / 脚本可靠调用 CLI
+- 你想快速查看命令风险级别、输出结构、示例
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--task <text>` | 否 | 任务文本（可重复传入）。 |
-| `--tasks <string\|@file>` | 否 | 任务列表（JSON 数组或逗号/换行分隔）。 |
-| `--title <string>` | 否 | 自定义笔记标题。 |
-| `--dry-run` | 否 | 仅预览将要创建的待办笔记，不实际写入。 |
+### 6.14 `daemon`：管理后台进程
 
-说明：`[task]`、`--task`、`--tasks` 至少提供一个。
+```bash
+dino daemon start
+dino daemon status
+dino daemon restart
+dino daemon stop
+```
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+调试时可以前台运行：
 
-### `dino todo update <taskId> --status <status>`
+```bash
+dino daemon start --no-detach
+```
 
-更新任务完成状态（按 taskId 定位）。
+`daemon` 是公开 CLI 模块，也可以通过 schema 查询：
 
-说明：
+```bash
+dino schema daemon.start --format json
+```
 
-- 只接受合法状态值：`completed` / `uncompleted`（兼容 `done` / `undone` / `true` / `false` / `1` / `0`）。
-- `content_json` 是真源，更新后会同步回写 `image_detail`、`content_md`、`content_text`。
-- 若同一个 taskId 出现在多篇笔记，会报错并拒绝更新（避免误改）。
+### 6.15 `info`：查看版本与技能仓库地址
 
-| 参数 | 必填 | 说明 |
-| --- | --- | --- |
-| `<taskId>` | 是 | 任务 ID。 |
+```bash
+dino info
+```
 
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `--status <status>` | 是 | 目标状态。 |
-| `--dry-run` | 否 | 仅预览将要更新的任务状态，不实际写入。 |
+### 6.16 `update`：升级 CLI
 
-支持全局参数：`--json`、`--format`、`--offline`、`--sync-timeout`
+```bash
+dino update
+```
 
 ---
 
-## 9. MCP Server 与 Cursor 配置
+## 7. AI / 脚本自动化
 
-`dino mcp serve` 会启动一个 HTTP JSON-RPC 服务，提供 Dinox 的 MCP tools 给 AI 客户端调用。
+如果你希望让 AI 助手或脚本可靠调用 Dinox 数据，推荐直接使用 CLI 命令的结构化输出。
 
-### 9.1 启动 MCP 服务
-
-默认监听本机 `127.0.0.1:45137`：
+### 7.1 使用 JSON 输出
 
 ```bash
-dino mcp serve
+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 解析。
+
+### 7.2 先读取命令 schema
+
+不确定某个命令支持哪些参数、输出哪些字段时，先读取 schema：
 
 ```bash
-dino mcp serve --host 127.0.0.1 --port 45137
+dino schema
+dino schema note.search --format json
+dino schema todo.update --format json
 ```
 
-### 9.2 局域网访问与鉴权
+schema 包含命令路径、风险级别、参数、选项、输出字段和示例。写操作建议先使用 `--dry-run` 确认结果。
 
-当 `--host` 为非回环地址（例如 `0.0.0.0`）时，必须提供 token：
+---
+
+## 8. 常见问题
+
+### Q1：报错 `Missing resolved userId for the current authorization`
+
+原因：你还没有完成登录，或当前 `DINOX_TOKEN` 环境变量覆盖了本地 token，CLI 需要先在线解析这个 token 对应的用户身份。
+
+解决：
 
 ```bash
-dino mcp serve --host 0.0.0.0 --port 45137 --token "<your-token>"
+dino auth login "<token>"
+dino sync
 ```
 
-也可以使用环境变量：
+如果你使用环境变量登录，确认 `DINOX_TOKEN` 已设置后直接运行一次在线命令：
 
 ```bash
-export DINOX_MCP_TOKEN="<your-token>"
-dino mcp serve --host 0.0.0.0 --port 45137
+dino auth status --format json
+dino sync
 ```
 
-请求头支持：
+### Q2：创建笔记时报 `Unknown tags` 或 `Unknown zettel box names`
 
-1. `Authorization: Bearer <token>`
-2. `x-dinox-token: <token>`
+原因：你引用了不存在的标签或卡片盒。
 
-### 9.3 快速连通性验证（curl）
+解决：先创建，再重试。
 
-初始化握手：
+```bash
+dino tag add "你的标签"
+dino box add "你的卡片盒"
+```
+
+### Q3：我已经同步过了，能不能完全离线查询？
+
+可以。很多读命令都支持：
 
 ```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
+--offline
 ```
 
-列出 tools：
+例如：
 
 ```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+dino note search "日报" --offline
+dino graph stats --offline --format json
 ```
 
-调用 tools（示例：搜索笔记）：
+前提是：你之前至少成功同步过一次，本地缓存里已经有数据。
+
+### Q4：`note update` 为什么不是“追加标签”？
+
+因为它的设计就是“全量替换”。
+
+例如：
 
 ```bash
-curl -X POST http://127.0.0.1:45137 \
-  -H 'content-type: application/json' \
-  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"dinox_search_notes","arguments":{"query":"dinox","limit":5}}}'
+dino note update <note-id> --tags "工作,AI"
 ```
 
-### 9.4 Cursor 配置示例
+执行后，目标笔记的标签会被替换成这两个，而不是在原来基础上追加。
+
+追加标签请使用：
+
+```bash
+dino note tag <note-id> --add "工作,AI"
+```
 
-可在以下位置创建 MCP 配置文件（任选其一）：
+### Q5：`todo append` 不传 `--note-id` 时会发生什么？
 
-1. 项目级：`.cursor/mcp.json`
-2. 全局：`~/.cursor/mcp.json`
+CLI 会自动选一条最近的、适合追加任务的笔记作为目标。
 
-推荐配置（带 token）：
+如果你不希望它自动选，最稳妥的做法是显式传：
 
-```json
-{
-  "mcpServers": {
-    "dinox": {
-      "url": "http://127.0.0.1:45137",
-      "headers": {
-        "Authorization": "Bearer ${env:DINOX_MCP_TOKEN}"
-      }
-    }
-  }
-}
+```bash
+dino todo append --note-id <note-id> --task "补交报销单"
 ```
 
-若本地仅回环访问且不启用 token，可去掉 `headers` 字段。
+### Q6：Windows 下 `@file` 参数解析不稳定怎么办？
 
-### 9.5 常见问题
+在 PowerShell 中，建议把 `@文件路径` 放进引号里。
 
-- 报错 `--token (or DINOX_MCP_TOKEN) is required when --host is non-loopback`：表示你使用了非回环 host，但没提供 token。
-- 返回 `401 Unauthorized`：检查请求头 token 是否与启动服务时一致。
-- 端口冲突：改用 `--port` 指定其他高位端口。
+例如：
 
----
+```powershell
+dino note create --title "测试" --content "@.\note.md" --type note
+```
 
-## 10. 查看帮助
+### Q7：怎么知道某个命令到底支持哪些参数？
 
-随时可以看帮助：
+最直接的方法：
 
 ```bash
-dino --help
 dino <命令> --help
-dino <命令> <子命令> --help
 ```
 
-例如：
+如果你想看更结构化的 schema：
 
 ```bash
-dino note --help
-dino note create --help
+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` | 覆盖同步超时 |
+
+### 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
 ```
 
 ---
 
-## 11. GitHub Action 自动发布 npm
+## 10. 如何查看帮助
 
-仓库已内置工作流：`/Users/shanks/Documents/GitHub/dinox-cli/.github/workflows/publish-npm.yml`
+任何时候都可以直接看 CLI 帮助：
 
-### 11.1 先配置 Secret
+```bash
+dino --help
+dino help note
+```
 
-在 GitHub 仓库设置里添加：
+更常见的写法是：
 
-- `NPM_TOKEN`：npm 的 publish token（建议使用 granular token，并开启 bypass 2FA）
+```bash
+dino note --help
+dino note create --help
+dino todo --help
+dino storage upload --help
+```
 
-### 11.2 手动触发发布
+如果你是脚本作者或 AI Agent 开发者，强烈建议搭配这两个命令一起使用：
 
-1. 打开 GitHub 仓库 → **Actions** → **Publish NPM**
-2. 点击 **Run workflow**
-3. 选择参数：
-   - `dry_run`：`true` 只做演练，不真正发布
-   - `run_tests`：`true` 时会先执行测试
+```bash
+dino schema
+dino schema <path> --format json
+```
 
-### 11.3 Push 自动触发
+---
 
-- 每次 push 到默认分支（当前为 `main`）会自动触发发布流程
-- 为兼容分支命名迁移，workflow 也监听 `master`，但发布阶段会只允许默认分支执行
-- 为防止递归触发，workflow 会跳过 `github-actions[bot]` 自己提交的版本 bump commit
+如果你是第一次用，建议按下面顺序熟悉：
 
-### 11.4 工作流行为
+1. `dino auth login`
+2. `dino sync`
+3. `dino note search`
+4. `dino note create`
+5. `dino todo search`
+6. `dino tag add` / `dino box add`
+7. `dino schema`
 
-- 只允许在仓库默认分支执行发布（默认分支改名后无需改 workflow 逻辑）
-- 调用仓库脚本 `publish-npm.sh` 自动递增 patch 版本并发布
-- 发布成功后自动提交 `package.json` 版本变更、打 `vX.Y.Z` tag 并 push 回仓库
+这样会最快建立完整使用感。