# 脚本与自动化

> 用 dino 的 JSON 输出、--select、命令 schema、batch 批量执行和结构化错误，把 Dinox 接进你的脚本、定时任务和 MCP 客户端。

- 网页：https://dinox.info/guides/cli/automation
- 本页 Markdown：https://dinox.info/guides/cli/automation.md
- 全部文档索引：https://dinox.info/llms.txt

`dino` 从一开始就是为「被程序调用」设计的：每条命令都能输出结构稳定的 JSON，错误也有固定的格式和下一步建议。本页讲怎么把它接进 Shell 脚本、定时任务、CI，或者任何 MCP 客户端。

## JSON 输出与 --select

任何命令加上 `--format json`（或 `--format yaml`）都返回统一的结构：

```json
{ "ok": true, "data": { … }, "_notice": … }
```

* 结果在 `data` 里；`_notice` 只在有提示（例如有新版本）时才出现。
* `--select` 只返回你要的字段，用逗号分隔，支持 `notes.id` 这样的路径。

```bash
dino note search 习惯 --tags 文档示例 --format json --select notes.id,notes.title
```

![截图：JSON 输出（--format json + --select：输出短而稳定，直接交给 jq 或脚本）](https://dinox.info/assets/docs/cli/json-output.webp)

配合 `jq` 一行取出所有标题：

```bash
dino note search --tags 文档示例 --format json --select notes.title | jq -r '.data.notes[].title'
```

## 不确定参数？先查 schema

```bash
dino schema               # 所有命令
dino schema note.search   # 某一条命令
```

![截图：dino schema note.search（命令的风险级别（read / write / high-risk-write）、全局参数、参数和每个选项的类型）](https://dinox.info/assets/docs/cli/schema.webp)

schema 比 `--help` 更适合程序读取：加 `--format json` 就能拿到完整的参数定义、输出字段和示例。AI 助手不确定用法时，Skills 也会让它先查 schema。

## 一次跑多条：dino batch

把多条命令写成一个 JSON 数组，一次执行、一次拿回所有结果，比反复启动 `dino` 快得多：

```json
[
  ["tag", "list", "--select", "count"],
  ["note", "search", "--tags", "文档示例", "--select", "meta.total_count"],
  ["todo", "search", "发布前检查清单", "--select", "meta.returned_count"]
]
```

```bash
dino batch --input batch.json
```

![截图：dino batch 批量执行（3 条命令全部成功；加 --format json 可以拿到每一条的完整结果）](https://dinox.info/assets/docs/cli/batch.webp)

默认某一条失败不影响其他条；加 `--stop-on-error` 则遇错即停，后面的标为 skipped。也可以用 `--input -` 从标准输入读取。

## 出错时：结构化错误

拼错参数、引用不存在的标签……`dino` 不会只丢一句「出错了」，而是告诉你**哪里错、能不能恢复、下一步该运行什么**：

![截图：结构化错误示例（拼错选项会提示正确写法；JSON 模式下返回 code、exit_code 和 suggested_action；不存在的标签会提示先运行 tag add）](https://dinox.info/assets/docs/cli/usage-error.webp)

JSON 模式下错误写在标准错误输出里，字段包括：

| 字段                 | 含义                    |
| ------------------ | --------------------- |
| `code`             | 错误类型，例如 `USAGE_ERROR` |
| `recoverable`      | 能否通过调整后重试来解决          |
| `exit_code`        | 进程退出码                 |
| `suggested_action` | 建议运行的下一条命令和原因         |

常见退出码：`0` 成功，`2` 用法错误，`3` 未登录或登录失效，`4` 数据不够新（例如用了 `--require-sync` 但没同步成功），`5` 前置条件不满足（例如笔记在你读取后被改过）。

## 写进脚本时的几条建议

* **给同步设上限**：在线命令加 `--sync-timeout 20000`，脚本自身的超时比它多 5–10 秒。
* **超时不等于失败**：脚本等不及退出，不代表写入没成功。重试写操作前，先查一下结果。
* **写入前预演**：`--dry-run` 返回的是计划，不会写入；确认无误再去掉。
* **需要上传完成再返回**：写命令默认写进本地就返回（`--durability local`）；想等它上传到云端，用 `--durability uploaded`。
* **不要用 `--json`**：这是旧参数，请用 `--format json`。
* **CI 登录**：用 `DINOX_TOKEN` 环境变量或 `dino auth login --token-stdin`，见 [安装与登录](https://dinox.info/guides/cli/install.md)。

## 接入 MCP 客户端

想在 Claude Desktop、Cursor 等支持 MCP 的客户端里用 Dinox，又希望数据走本机？`dino mcp` 会以 stdio 方式把 Dinox 命令提供为 MCP 工具：

```json
{
  "mcpServers": {
    "dinox": { "command": "dino", "args": ["mcp", "--read-only"] }
  }
}
```

* `--read-only` 只开放读取类工具。
* `--groups note,todo,tag` 只开放指定分组（可选 note、tag、box、todo、view、prop、template、prompt、graph、storage、stats）。

> **提示**
> 不想在本机装 CLI、或者要连 ChatGPT、豆包等在线 AI，请用托管的 [Dinox MCP](https://dinox.info/guides/mcp.md)。想在 Codex 侧边栏里和 AI 一起编辑笔记，请看 [和 AI 一起编辑笔记](https://dinox.info/guides/desktop/editor.md)（由 `dino editor` 提供）。直接调用 HTTP 接口，请看 [开放接口](https://dinox.info/guides/api/openapi.md)。

## 体检结果也能给程序看

监控脚本可以定时跑一次 `doctor`，`healthy` 不是 `true` 就报警：

```bash
dino doctor --format json --select healthy,sync.status,issues
```

![截图：doctor 的 JSON 输出（healthy + 各项状态 + issues，适合接进监控）](https://dinox.info/assets/docs/cli/doctor-json.webp)